# taskpaper-mcp

MCP server for reading and writing [TaskPaper](https://www.taskpaper.com) plain text files. No AppleScript needed, works directly with the `.taskpaper` file format.

## Install

```bash
npm install -g taskpaper-mcp
```

Or use without installing:

```bash
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

```json
{
  "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