TaskChampion MCP

A Model Context Protocol server for Taskwarrior 3.x, TaskChampion, and Timewarrior.

> *For the bearded Unix jockeys and keyboard cowboys who manage their life from the terminal — and now want their LLM to lend a hand.* 🧔⌨️

Latest release: v1.0.4 — `pip install taskchampion-mcp` / `uvx taskchampion-mcp`

What Is This?

TaskChampion MCP is a Model Context Protocol server that lets LLMs read, create, modify, and manage your Taskwarrior tasks and Timewarrior time entries. It wraps the `task` and `timew` CLI tools and exposes them as structured MCP tools that any compatible AI assistant can call.

Why? The author self-hosts TaskChampion on a home server and wanted a clean way for LLMs to cooperate on project planning, task decomposition, and time tracking — without giving up control of the task database.

Supported Platforms

Requirements:

• Python 3.10+
• Taskwarrior 3.x (TaskChampion sync)
• Timewarrior (optional, for time tracking features)

Quick Install

# With uv (recommended)
uv tool install taskchampion-mcp

# With pip
pip install taskchampion-mcp

Then configure your IDE's MCP settings to use:

{
  "mcpServers": {
    "taskchampion": {
      "command": "taskchampion-mcp-server",
      "args": []
    }
  }
}

Per-target install guides: Claude Desktop | Windsurf | Cursor | Neovim

First Run

On a fresh install with no `config.toml`, the server boots in onboarding mode. All tools are visible in `tools/list`, but operational tools return structured `schema_unset` errors until onboarding completes (ADR 19). You finish onboarding by persisting two keys in `~/.config/taskchampion-mcp/config.toml`:

• `role` — what the LLM can do (CONTRIBUTOR / GENERATOR / MANAGER)
• `schema` *or* `schema_path` — which task schema the server validates against

Three ways to get there:

1. Let the LLM walk you through it. Connect your IDE to the MCP server with no config and ask: *"Help me set up TaskChampion MCP."* The LLM calls `get_runtime_capabilities` first, sees `mode: "onboarding"`, then uses `get_initialization_status` -> `propose_initialization_options` -> `use_preset_schema` (or `save_initial_schema`). The server auto-reloads on success -- no restart needed.

2. Run the CLI wizard: `./dev.sh init` (interactive) or `./dev.sh init --preset gtd --role CONTRIBUTOR --non-interactive` (scripted).

3. Edit `config.toml` by hand -- see quick_start.md. Two keys, then call `reload_configuration` from the LLM (or restart the IDE).

The three paths are interchangeable and produce identical state. Pick by who should be doing the typing -- see initialization_flows.md for the decision guide.

Permission Levels

Control what the LLM can do with your tasks via three cumulative roles:

Set the role in `~/.config/taskchampion-mcp/config.toml`:

[server]
role = "GENERATOR"  # CONTRIBUTOR | GENERATOR | MANAGER

Task Schemas

Taskwarrior supports custom workflows via UDAs (User Defined Attributes). TaskChampion MCP ships with schema presets that teach the LLM your task structure:

On first run, the MCP will prompt you to select a schema or auto-generate one from your existing tasks.

Security

This tool gives an LLM indirect access to your task management CLI. Security is not optional:

• No shell execution — all CLI calls use subprocess argument lists, never `shell=True`
• Input sanitization — all LLM inputs validated against allowlists before passing to CLI
• Rate limiting — configurable per-minute/per-hour caps prevent runaway loops
• Audit logging — every operation logged with timestamp, tool, parameters, result, and `result_code`
• Code-tagged envelopes — every tool response includes a stable `code` field for machine-safe branching
• Dry-run mode — every destructive operation supports `dry_run` preview without mutation
• Confirmation mode — lifecycle operations use explicit confirmation tokens when confirmation is enabled
• Sensitive field redaction — configurable fields hidden from LLM responses

See ADR 9, ADR 13, and ADR 14 for the full security and observability design.

Taskwarrior Compatibility

We focus on the modern Taskwarrior 3.x + TaskChampion stack. Taskserver (taskd) is deprecated and will receive limited support in a future version. See ADR 8.

Documentation

Troubleshooting

Common first-run and config issues. Detailed walkthroughs live in docs/manuals/quick_start.md and docs/manuals/initialization_flows.md.

For deeper failure modes, every MCP tool returns a stable `error_code` field (ADR 14) and every call is audit-logged (ADR 13) at `~/.local/share/taskchampion-mcp/audit.log` by default.

Contributing

See `docs/CONTRIBUTING.md` for the full guide. Key points:

• Branch from `dev`, PR to `qa`, release from `qa` to `main`
• Semantic versioning (`vMAJOR.MINOR.PATCH`)
• LLM-assisted contributions must be attributed (see `docs/llm_context/AGENTS.md`)
• All unverified assumptions must be logged in `docs/llm_context/assumptions_and_ideas.md`

License

Apache License 2.0 — use freely for private and commercial purposes. Attribution required via the NOTICE file.

Copyright 2026 gabiup2

*This project was bootstrapped with assistance from Claude claude-sonnet-4-20250514 via Windsurf Cascade.*