task-warrior-mcp

A Model Context Protocol server that wraps the Taskwarrior CLI. Gives Claude (or any MCP client) structured, project-scoped access to your tasks.

Why project-scoped?

Every read and write operation requires a project field. The server automatically prepends project:<name> to all Taskwarrior queries. Without this, a single task next call can dump thousands of unrelated tasks into your LLM's context — slow, expensive, and useless. An explicit all_projects boolean opt-out exists for the rare cases that genuinely need a global view.

Requirements

Taskwarrior (task on $PATH)

Installation

From MCP Registry (recommended)

Find task-warrior-mcp on the MCP Registry and follow the installation prompt in your MCP client. No build step required.

From source

Requires Rust (stable).

git clone https://github.com/<you>/task-warrior-mcp
cd task-warrior-mcp
cargo build --release

The binary lands at target/release/task-warrior-mcp.

Configuration

Claude Code (global, all sessions)

If installed via the MCP registry, your client handles configuration automatically. For a local build:

claude mcp add --scope user taskwarrior /path/to/task-warrior-mcp/target/release/task-warrior-mcp

Claude Desktop

Merge the snippet below into your claude_desktop_config.json (replace <INSTALL_DIR> with the absolute path to this repo):

{
  "mcpServers": {
    "taskwarrior": {
      "command": "<INSTALL_DIR>/target/release/task-warrior-mcp",
      "args": []
    }
  }
}

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Linux: ~/.config/Claude/claude_desktop_config.json

Tools

Tool	Required	Optional
`add_task`	`description`, `project`	`due`, `tags`, `priority`, `wait`, `scheduled`
`list_tasks`	`project`	`filter`, `report`, `all_projects`
`search_tasks`	`pattern`, `project`	`filter`, `all_projects`
`get_task`	`id`	—
`modify_task`	`id`, `modifications`	—
`complete_task`	`id`	—
`delete_task`	`id`	—
`annotate_task`	`id`, `note`	—

Date syntax

today · tomorrow · eow · eom · friday · 2025-06-15 · 2025-06-15T14:30 · today+3d · later

Filter virtual tags

+OVERDUE · +DUE · +TODAY · +READY · +ACTIVE · +BLOCKED · +BLOCKING · +WAITING

Reports

next (default, urgency-sorted) · list · all · completed · waiting · blocked

Priorities

H (high) · M (medium) · L (low)

Development

just build          # cargo build --release
just test           # run all tests (each isolated in a temp taskwarrior DB)
just lint           # clippy + fmt check

Or use cargo directly:

cargo test
cargo clippy
cargo fmt

A pre-push hook runs fmt + clippy + tests automatically — no setup needed after cloning.

CI runs the same checks on every push and PR via GitHub Actions.

Releasing

Requires: just, gh, jq, openssl, and cargo-edit (just setup).

just setup                  # install cargo-edit (one-time)
just release                # bump patch, build, push tag, create GitHub release, update server.json
just release minor          # bump minor version
just release-version 1.2.3  # explicit version
just publish                # push server.json to the MCP registry (after mcp-publisher login)

Taskwarrior MCP