{
  "markdown": "# TaskChampion MCP\n\n**A Model Context Protocol server for Taskwarrior 3.x, TaskChampion, and Timewarrior.**\n\n> *For the bearded Unix jockeys and keyboard cowboys who manage their life from the terminal — and now want their LLM to lend a hand.* 🧔⌨️\n\n<!-- mcp-name: io.github.GabiUp2/taskchampion-mcp -->\n\n[![PyPI version](https://img.shields.io/pypi/v/taskchampion-mcp.svg)](https://pypi.org/project/taskchampion-mcp/)\n[![GitHub release](https://img.shields.io/github/v/release/GabiUp2/TaskChampion_MCP.svg)](https://github.com/GabiUp2/TaskChampion_MCP/releases)\n[![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](LICENSE)\n[![Python](https://img.shields.io/badge/python-3.10+-green.svg)](https://python.org)\n[![MCP Registry](https://img.shields.io/badge/MCP-Registry-blue)](https://registry.modelcontextprotocol.io/v0/servers?search=io.github.GabiUp2/taskchampion-mcp)\n[![Glama](https://glama.ai/mcp/servers/GabiUp2/TaskChampion_MCP/badges/score.svg)](https://glama.ai/mcp/servers/GabiUp2/TaskChampion_MCP)\n\n**Latest release:** [v1.0.4](https://github.com/GabiUp2/TaskChampion_MCP/releases/tag/v1.0.4) — [`pip install taskchampion-mcp`](https://pypi.org/project/taskchampion-mcp/) / `uvx taskchampion-mcp`\n\n---\n\n## What Is This?\n\nTaskChampion MCP is a [Model Context Protocol](https://modelcontextprotocol.io) 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.\n\n**Why?** The author self-hosts [TaskChampion](https://github.com/GothenburgBitFactory/taskchampion-sync-server) 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.\n\n---\n\n## Supported Platforms\n\n| Platform | Transport | Status |\n|---|---|---|\n| **Neovim** (via Claude Code CLI) | stdio | v1.0.4 |\n| **Cursor** | stdio | v1.0.4 |\n| **Windsurf** | stdio | v1.0.4 |\n| **VS Code** (Copilot MCP) | stdio | v1.0.4 |\n| **Claude Desktop** | stdio | v1.0.4 |\n| **HTTP/SSE transports** | HTTP/SSE | Deferred to v1.x |\n\n**Requirements:**\n- Python 3.10+\n- Taskwarrior 3.x (TaskChampion sync)\n- Timewarrior (optional, for time tracking features)\n\n---\n\n## Quick Install\n\n```bash\n# With uv (recommended)\nuv tool install taskchampion-mcp\n\n# With pip\npip install taskchampion-mcp\n```\n\nThen configure your IDE's MCP settings to use:\n```json\n{\n  \"mcpServers\": {\n    \"taskchampion\": {\n      \"command\": \"taskchampion-mcp-server\",\n      \"args\": []\n    }\n  }\n}\n```\n\nPer-target install guides: [Claude Desktop](docs/manuals/targets/claude_desktop.md) | [Windsurf](docs/manuals/targets/windsurf.md) | [Cursor](docs/manuals/targets/cursor.md) | [Neovim](docs/manuals/targets/neovim.md)\n\n---\n\n## First Run\n\nOn 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`:\n\n- `role` — what the LLM can do (CONTRIBUTOR / GENERATOR / MANAGER)\n- `schema` *or* `schema_path` — which task schema the server validates against\n\nThree ways to get there:\n\n1. **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**.\n2. **Run the CLI wizard:** `./dev.sh init` (interactive) or `./dev.sh init --preset gtd --role CONTRIBUTOR --non-interactive` (scripted).\n3. **Edit `config.toml` by hand** -- see [quick_start.md](docs/manuals/quick_start.md). Two keys, then call `reload_configuration` from the LLM (or restart the IDE).\n\nThe three paths are interchangeable and produce identical state. Pick by who should be doing the typing -- see [initialization_flows.md](docs/manuals/initialization_flows.md) for the decision guide.\n\n---\n\n## Permission Levels\n\nControl what the LLM can do with your tasks via three cumulative roles:\n\n| Role | Can Read | Can Annotate/Modify | Can Create | Can Complete/Delete |\n|---|---|---|---|---|\n| **CONTRIBUTOR** | ✅ | ✅ | ❌ | ❌ |\n| **GENERATOR** | ✅ | ✅ | ✅ | ❌ |\n| **MANAGER** | ✅ | ✅ | ✅ | ✅ |\n\nSet the role in `~/.config/taskchampion-mcp/config.toml`:\n```toml\n[server]\nrole = \"GENERATOR\"  # CONTRIBUTOR | GENERATOR | MANAGER\n```\n\n---\n\n## Task Schemas\n\nTaskwarrior supports custom workflows via UDAs (User Defined Attributes). TaskChampion MCP ships with schema presets that teach the LLM your task structure:\n\n| Schema | Description |\n|---|---|\n| `minimal` | Built-in fields only (priority, project, tags) |\n| `gtd` | Getting Things Done (contexts, energy, next-actions) |\n| `scrum` | Sprint-based (story points, sprint IDs, acceptance criteria) |\n| `kanban` | Board columns, WIP limits, classes of service |\n| `authors_custom_example` | Advanced real-world example with lifecycle phases, hypothesis-driven research, and LLM provenance tracking |\n\nOn first run, the MCP will prompt you to select a schema or auto-generate one from your existing tasks.\n\n---\n\n## Security\n\nThis tool gives an LLM indirect access to your task management CLI. Security is not optional:\n\n- **No shell execution** — all CLI calls use subprocess argument lists, never `shell=True`\n- **Input sanitization** — all LLM inputs validated against allowlists before passing to CLI\n- **Rate limiting** — configurable per-minute/per-hour caps prevent runaway loops\n- **Audit logging** — every operation logged with timestamp, tool, parameters, result, and `result_code`\n- **Code-tagged envelopes** — every tool response includes a stable `code` field for machine-safe branching\n- **Dry-run mode** — every destructive operation supports `dry_run` preview without mutation\n- **Confirmation mode** — lifecycle operations use explicit confirmation tokens when confirmation is enabled\n- **Sensitive field redaction** — configurable fields hidden from LLM responses\n\nSee [ADR 9](docs/adrs/ADRs.md), [ADR 13](docs/adrs/ADRs.md), and [ADR 14](docs/adrs/ADRs.md) for the full security and observability design.\n\n---\n\n## Taskwarrior Compatibility\n\n| Version | Status |\n|---|---|\n| **Taskwarrior 3.x** (TaskChampion) | ✅ Fully supported |\n| **Taskwarrior 2.x** (Taskserver/taskd) | ⏳ Planned for future release |\n\nWe 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](docs/adrs/ADRs.md).\n\n---\n\n## Documentation\n\n| Folder / file | Contents |\n|---|---|\n| [`docs/adrs/`](docs/adrs/) | Architecture Decision Records |\n| [`docs/references/`](docs/references/) | Upstream tool reference (Taskd, TaskChampion, Timewarrior) |\n| [`docs/manuals/quick_start.md`](docs/manuals/quick_start.md) | Manual `config.toml` setup |\n| [`docs/manuals/configuration_reference.md`](docs/manuals/configuration_reference.md) | Full config key reference with precedence rules |\n| [`docs/manuals/schema_authoring.md`](docs/manuals/schema_authoring.md) | Writing custom task schemas |\n| [`docs/manuals/security_model.md`](docs/manuals/security_model.md) | Security controls for end-users |\n| [`docs/manuals/initialization_flows.md`](docs/manuals/initialization_flows.md) | Which init path to use (LLM-driven vs CLI vs hand-edit) |\n| [`docs/manuals/targets/`](docs/manuals/targets/) | Per-IDE install guides (Claude Desktop, Windsurf, Cursor, Neovim) |\n| [`docs/manuals/logrotate.md`](docs/manuals/logrotate.md) | Audit log rotation |\n| [`docs/llm_context/`](docs/llm_context/) | LLM agent guidelines and tracked assumptions |\n| [`docs/CONTRIBUTING.md`](docs/CONTRIBUTING.md) | How to contribute (branching, PRs, versioning) |\n| [`docs/ROADMAP.md`](docs/ROADMAP.md) | Feature roadmap (v0.1.0 → v1.0.0) |\n| [`docs/releases/v1.0.4.md`](docs/releases/v1.0.4.md) | v1.0.2 release notes and install links |\n| [`docs/manuals/release_checklist.md`](docs/manuals/release_checklist.md) | Pre-tag publish checklist |\n| [`src/taskchampion_mcp/schemas/`](src/taskchampion_mcp/schemas/) | Bundled task schema presets (TOML) |\n| [`scripts/setup_remote.sh`](scripts/setup_remote.sh) | One-shot remote-host bootstrap |\n\n---\n\n## Troubleshooting\n\nCommon first-run and config issues. Detailed walkthroughs live in [docs/manuals/quick_start.md](docs/manuals/quick_start.md) and [docs/manuals/initialization_flows.md](docs/manuals/initialization_flows.md).\n\n| Symptom | Likely cause | Fix |\n|---|---|---|\n| Tools return `schema_unset` errors after connecting | `~/.config/taskchampion-mcp/config.toml` is missing either `role` or `schema`/`schema_path` | Add both under `[server]` and call `reload_configuration` (or restart). |\n| Linux Claude Desktop install completes but taskchampion never appears | Pre-v0.3.0 lowercase path bug in dev.sh | Update to v0.3.0+. Linux: capital `C` in `~/.config/Claude/`. |\n| `set_role(\"MANAGER\")` returns `role_elevation_forbidden` | Self-elevation via MCP is forbidden ([ADR 17](docs/adrs/ADRs.md)) | Hand-edit `config.toml`, then call `reload_configuration`. |\n| MCP server fails on startup with `Taskwarrior not found on PATH` | `task` not installed or not on the MCP server's `PATH` | Install Taskwarrior 3.x. Set `task_binary` in config if needed. |\n| Cowork / Claude Desktop: install JSON overwritten on quit | Wrote config while Claude Desktop was running | Quit Claude Desktop first, or use `./dev.sh reinstall claude -r`. |\n| Tool surface includes neither onboarding nor contributor tools | Server failed to start (check stderr) | Run `taskchampion-mcp-server` from a shell to see the error. |\n\nFor deeper failure modes, every MCP tool returns a stable `error_code` field ([ADR 14](docs/adrs/ADRs.md)) and every call is audit-logged ([ADR 13](docs/adrs/ADRs.md)) at `~/.local/share/taskchampion-mcp/audit.log` by default.\n\n---\n\n## Contributing\n\nSee [`docs/CONTRIBUTING.md`](docs/CONTRIBUTING.md) for the full guide. Key points:\n\n- Branch from `dev`, PR to `qa`, release from `qa` to `main`\n- Semantic versioning (`vMAJOR.MINOR.PATCH`)\n- LLM-assisted contributions must be attributed (see [`docs/llm_context/AGENTS.md`](docs/llm_context/AGENTS.md))\n- All unverified assumptions must be logged in [`docs/llm_context/assumptions_and_ideas.md`](docs/llm_context/assumptions_and_ideas.md)\n\n---\n\n## License\n\n[Apache License 2.0](LICENSE) — use freely for private and commercial purposes. Attribution required via the [NOTICE](NOTICE) file.\n\nCopyright 2026 gabiup2\n\n---\n\n*This project was bootstrapped with assistance from Claude claude-sonnet-4-20250514 via Windsurf Cascade.*\n",
  "bytes": 10887,
  "sha": "661aa68598e528fb6e186e7af2a1e8ae01b6a6fbdfa834c56218e0ac34029ff8",
  "repo_slug": "gabiup2/taskchampion_mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_gabiup2_taskchampion_mcp_1b23f52e/readme"
}