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