taskpaper-mcp

MCP server for reading and writing TaskPaper plain text files. No AppleScript needed, works directly with the .taskpaper file format.

Install

npm install -g taskpaper-mcp

Or use without installing:

npx taskpaper-mcp

Configuration

Set TASKPAPER_DIR to the directory containing your .taskpaper files. If not set, defaults to $HOME.

Kiro CLI / Claude Desktop / any MCP client

{
  "mcpServers": {
    "taskpaper": {
      "command": "npx",
      "args": ["taskpaper-mcp"],
      "env": {
        "TASKPAPER_DIR": "/path/to/your/taskpaper/files"
      }
    }
  }
}

Tools

| Tool | Description | |------|-------------| | list_files | List all .taskpaper files in the configured directory | | list_projects | List all projects with task/done counts | | list_tasks | List tasks, filter by project, tag, or done status | | list_tags | List all unique tags with distinct value counts and values | | search | Search items by text, tag, or type | | read_file | Full parsed outline as structured JSON | | add_task | Add a task (optionally under a project, with tags and note) | | add_tasks | Batch add multiple tasks in one operation | | add_project | Add a new project | | add_projects | Batch add multiple projects | | add_note | Add a note under a project or task | | add_tag | Add any tag to matching items | | add_tags | Batch add tags to multiple items | | remove_tag | Remove a tag from matching items | | modify_tag | Change a tag's value on matching items | | complete_task | Toggle @done on matching tasks | | archive_done | Move all @done items to Archive project | | move_task | Move a task to a different project |

TaskPaper Format

Plain text. Each line is an item:

• Project: line ending with : (e.g. Groceries:)
• Task: line starting with - (e.g. - Buy milk)
• Note: anything else
• Tags: @name or @name(value) anywhere on a line
• Hierarchy: tab indentation

All tags are supported. Common conventions: @done, @due(date), @priority(n), @today, @flagged.

License

MIT