MCP server for reading and writing TaskPaper plain text files. No AppleScript needed, works directly with the .taskpaper file format.
npm install -g taskpaper-mcpOr use without installing:
npx taskpaper-mcpSet TASKPAPER_DIR to the directory containing your .taskpaper files. If not set, defaults to $HOME.
{
"mcpServers": {
"taskpaper": {
"command": "npx",
"args": ["taskpaper-mcp"],
"env": {
"TASKPAPER_DIR": "/path/to/your/taskpaper/files"
}
}
}
}This server writes to your files in place. It does not keep backups, and there is no undo. A bad write is only recoverable from whatever you had going in externally (git, Time Machine, iCloud versions, etc.).
The recommended setup is a git repository at TASKPAPER_DIR. Commit
before and after any session that uses the write tools below (everything
in the second half of the table). That way git diff shows exactly what
changed, and git checkout reverts anything unexpected. A one-line note
in your project's CLAUDE.md or agent instructions (something like "the
taskpaper-mcp writes in place; commit before and after any write
session") is enough to get Claude to do this too.
The edit_text, delete_item, move_task, complete_task, add_tag,
remove_tag, modify_tag, and add_note tools refuse to act when a
text substring matches more than one item (pass match_all: true to
override), and accept a line: argument for exact addressing. Combined
with the git-commit habit, that covers the common classes of
accident — a too-generic match, or a change you didn't mean to make.
| 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, done status, overdue, or upcoming_days |
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 |
edit_text |
Change the body text of matching items |
delete_item |
Delete matching items and their descendants |
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:
@nameor@name(value)anywhere on a line - Hierarchy: tab indentation
All tags are supported. Common conventions: @done, @due(date), @priority(n), @today, @flagged.
This server aims to match the canonical TaskPaper format as implemented by BirchOutline, so that files edited here remain fully interoperable with the original TaskPaper macOS editor and other tooling.
Known remaining gaps (not yet exercised by tests):
- Tag names containing Unicode letters outside
[A-Za-z0-9_.-]are not recognised; canonical permits a wider range. - The tag regex has no trailing lookahead, so
@foo:barmatches@fooas a tag. Canonical requires a tag to be followed by whitespace or end-of-line.
MIT
