TaskChampion MCP

io.github.GabiUp2Published by GitHub account GabiUp2v1.0.4Updated Oct 24, 2026

MCP server for Taskwarrior 3.x, TaskChampion, and Timewarrior task management.

VerifiedSTDIODesktop onlyProductivity & WorkflowDeveloper Tools

Overview

AI-generated overview

Lets an AI assistant read, create, modify, and complete Taskwarrior 3.x tasks and Timewarrior time entries through the local task and timew CLIs.

What you can do
Wraps the task and timew command-line tools and exposes them as structured MCP tools, so an assistant can read, annotate, create, complete, and delete tasks and manage time entries. It ships task schema presets (minimal, gtd, scrum, kanban, and a custom example) that describe your task structure to the model. A first-run onboarding flow sets a role and schema, and tools include get_runtime_capabilities, get_initialization_status, propose_initialization_options, use_preset_schema, save_initial_schema, and reload_configuration.
When to use it
Use it when you already manage tasks and time in Taskwarrior 3.x or Timewarrior and want an assistant to help with project planning, task decomposition, and time tracking without handing over your task database. It suits terminal-centric workflows on a local machine.
Requirements
Local process over stdio, installed from PyPI as taskchampion-mcp and run with uvx or pip. Needs Python 3.10+, Taskwarrior 3.x on PATH, and optionally Timewarrior for time tracking. A config file at ~/.config/taskchampion-mcp/config.toml must set role and schema or schema_path before operational tools work. No authentication, environment variables, or headers are declared.
Before you install
The server gives an assistant indirect write access to your task CLI, so role matters: CONTRIBUTOR can read and modify, GENERATOR can also create, and MANAGER can also complete and delete. Self-elevation to MANAGER through MCP is refused, so role changes require hand-editing config.toml. Destructive operations support dry_run and confirmation tokens, and operations are audit-logged by default; review the role and confirmation settings before connecting.

Installation

In SourceWeft

  1. Open TaskChampion MCP in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.

Other MCP clients

Follow the launch instructions in the repository.

README

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. 🧔⌨️

[PyPI version] [GitHub release] [License] [Python] [MCP Registry] [Glama]

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

PlatformTransportStatus
Neovim (via Claude Code CLI)stdiov1.0.4
Cursorstdiov1.0.4
Windsurfstdiov1.0.4
VS Code (Copilot MCP)stdiov1.0.4
Claude Desktopstdiov1.0.4
HTTP/SSE transportsHTTP/SSEDeferred to v1.x

Requirements:

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

Quick Install

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

Then configure your IDE's MCP settings to use:

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

RoleCan ReadCan Annotate/ModifyCan CreateCan Complete/Delete
CONTRIBUTOR✅✅❌❌
GENERATOR✅✅✅❌
MANAGER✅✅✅✅

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

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:

SchemaDescription
minimalBuilt-in fields only (priority, project, tags)
gtdGetting Things Done (contexts, energy, next-actions)
scrumSprint-based (story points, sprint IDs, acceptance criteria)
kanbanBoard columns, WIP limits, classes of service
authors_custom_exampleAdvanced real-world example with lifecycle phases, hypothesis-driven research, and LLM provenance tracking

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

VersionStatus
Taskwarrior 3.x (TaskChampion)✅ Fully supported
Taskwarrior 2.x (Taskserver/taskd)⏳ Planned for future release

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

Folder / fileContents
docs/adrs/Architecture Decision Records
docs/references/Upstream tool reference (Taskd, TaskChampion, Timewarrior)
docs/manuals/quick_start.mdManual config.toml setup
docs/manuals/configuration_reference.mdFull config key reference with precedence rules
docs/manuals/schema_authoring.mdWriting custom task schemas
docs/manuals/security_model.mdSecurity controls for end-users
docs/manuals/initialization_flows.mdWhich init path to use (LLM-driven vs CLI vs hand-edit)
docs/manuals/targets/Per-IDE install guides (Claude Desktop, Windsurf, Cursor, Neovim)
docs/manuals/logrotate.mdAudit log rotation
docs/llm_context/LLM agent guidelines and tracked assumptions
docs/CONTRIBUTING.mdHow to contribute (branching, PRs, versioning)
docs/ROADMAP.mdFeature roadmap (v0.1.0 → v1.0.0)
docs/releases/v1.0.4.mdv1.0.2 release notes and install links
docs/manuals/release_checklist.mdPre-tag publish checklist
src/taskchampion_mcp/schemas/Bundled task schema presets (TOML)
scripts/setup_remote.shOne-shot remote-host bootstrap

Troubleshooting

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

SymptomLikely causeFix
Tools return schema_unset errors after connecting~/.config/taskchampion-mcp/config.toml is missing either role or schema/schema_pathAdd both under [server] and call reload_configuration (or restart).
Linux Claude Desktop install completes but taskchampion never appearsPre-v0.3.0 lowercase path bug in dev.shUpdate to v0.3.0+. Linux: capital C in ~/.config/Claude/.
set_role("MANAGER") returns role_elevation_forbiddenSelf-elevation via MCP is forbidden (ADR 17)Hand-edit config.toml, then call reload_configuration.
MCP server fails on startup with Taskwarrior not found on PATHtask not installed or not on the MCP server's PATHInstall Taskwarrior 3.x. Set task_binary in config if needed.
Cowork / Claude Desktop: install JSON overwritten on quitWrote config while Claude Desktop was runningQuit Claude Desktop first, or use ./dev.sh reinstall claude -r.
Tool surface includes neither onboarding nor contributor toolsServer failed to start (check stderr)Run taskchampion-mcp-server from a shell to see the error.

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:

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.

Source: README.md at commit f5af773

Tools

0
SourceWeft has not started this package in its sandbox yet, so its tools are not known.

Version history

1
  1. v1.0.4LatestSep 16, 2026

Score

50% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 days25 pts

    Keep the endpoint answering the MCP handshake; SourceWeft probes it every 30 days.

  • Auth declared10 pts

    Declare the credential headers in the registry entry, or keep the endpoint answering the probe so its auth can be classified.

  • Tools listed15 pts

    Answer tools/list without a credential, or ship a package that starts in a sandbox without one.

  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts