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.