Server data from the Official MCP Registry
MCP server for Taskwarrior 3.x, TaskChampion, and Timewarrior task management.
MCP server for Taskwarrior 3.x, TaskChampion, and Timewarrior task management.
TaskChampion MCP is a well-architected MCP server for Taskwarrior task management with strong security foundations. The codebase demonstrates careful attention to security patterns: no shell injection vulnerabilities, proper input validation via allowlists, structured error envelopes (ADR 14), rate limiting, and comprehensive audit logging. Permissions are appropriately scoped to task/time management operations matching the server's stated purpose. Minor code quality findings and some informational recommendations exist, but do not indicate exploitable vulnerabilities. Supply chain analysis found 3 known vulnerabilities in dependencies (0 critical, 3 high severity). Package verification found 1 issue.
3 files analyzed · 9 issues found
Security scores are indicators to help you make informed decisions, not guarantees. Always review permissions before connecting any MCP server.
This plugin requests these system permissions. Most are normal for its category.
Add this to your MCP configuration file:
{
"mcpServers": {
"io-github-gabiup2-taskchampion-mcp": {
"args": [
"taskchampion-mcp"
],
"command": "uvx"
}
}
}From the project's GitHub README.
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.0 — pip install taskchampion-mcp / uvx taskchampion-mcp
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.
| Platform | Transport | Status |
|---|---|---|
| Neovim (via Claude Code CLI) | stdio | v1.0.0 |
| Cursor | stdio | v1.0.0 |
| Windsurf | stdio | v1.0.0 |
| VS Code (Copilot MCP) | stdio | v1.0.0 |
| Claude Desktop | stdio | v1.0.0 |
| HTTP/SSE transports | HTTP/SSE | Deferred to v1.x |
Requirements:
# 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
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 againstThree ways to get there:
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../dev.sh init (interactive) or ./dev.sh init --preset gtd --role CONTRIBUTOR --non-interactive (scripted).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.
Control what the LLM can do with your tasks via three cumulative roles:
| Role | Can Read | Can Annotate/Modify | Can Create | Can Complete/Delete |
|---|---|---|---|---|
| CONTRIBUTOR | ✅ | ✅ | ❌ | ❌ |
| GENERATOR | ✅ | ✅ | ✅ | ❌ |
| MANAGER | ✅ | ✅ | ✅ | ✅ |
Set the role in ~/.config/taskchampion-mcp/config.toml:
[server]
role = "GENERATOR" # CONTRIBUTOR | GENERATOR | MANAGER
Taskwarrior supports custom workflows via UDAs (User Defined Attributes). TaskChampion MCP ships with schema presets that teach the LLM your task structure:
| Schema | Description |
|---|---|
minimal | Built-in fields only (priority, project, tags) |
gtd | Getting Things Done (contexts, energy, next-actions) |
scrum | Sprint-based (story points, sprint IDs, acceptance criteria) |
kanban | Board columns, WIP limits, classes of service |
authors_custom_example | Advanced 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.
This tool gives an LLM indirect access to your task management CLI. Security is not optional:
shell=Trueresult_codecode field for machine-safe branchingdry_run preview without mutationSee ADR 9, ADR 13, and ADR 14 for the full security and observability design.
| Version | Status |
|---|---|
| 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.
| Folder / file | Contents |
|---|---|
docs/adrs/ | Architecture Decision Records |
docs/references/ | Upstream tool reference (Taskd, TaskChampion, Timewarrior) |
docs/manuals/quick_start.md | Manual config.toml setup |
docs/manuals/configuration_reference.md | Full config key reference with precedence rules |
docs/manuals/schema_authoring.md | Writing custom task schemas |
docs/manuals/security_model.md | Security controls for end-users |
docs/manuals/initialization_flows.md | Which 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.md | Audit log rotation |
docs/llm_context/ | LLM agent guidelines and tracked assumptions |
docs/CONTRIBUTING.md | How to contribute (branching, PRs, versioning) |
docs/ROADMAP.md | Feature roadmap (v0.1.0 → v1.0.0) |
docs/releases/v1.0.0.md | v1.0.0 release notes and install links |
docs/manuals/release_checklist.md | Pre-tag publish checklist |
src/taskchampion_mcp/schemas/ | Bundled task schema presets (TOML) |
scripts/setup_remote.sh | One-shot remote-host bootstrap |
Common first-run and config issues. Detailed walkthroughs live in docs/manuals/quick_start.md and docs/manuals/initialization_flows.md.
| Symptom | Likely cause | Fix |
|---|---|---|
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). |
| 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/. |
set_role("MANAGER") returns role_elevation_forbidden | Self-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 PATH | task not installed or not on the MCP server's PATH | Install Taskwarrior 3.x. Set task_binary in config if needed. |
| 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. |
| 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. |
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.
See docs/CONTRIBUTING.md for the full guide. Key points:
dev, PR to qa, release from qa to mainvMAJOR.MINOR.PATCH)docs/llm_context/AGENTS.md)docs/llm_context/assumptions_and_ideas.mdApache 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.
Be the first to review this server!
by Modelcontextprotocol · Developer Tools
Read, search, and manipulate Git repositories programmatically
by Toleno · Developer Tools
Toleno Network MCP Server — Manage your Toleno mining account with Claude AI using natural language.
by mcp-marketplace · Developer Tools
Create, build, and publish Python MCP servers to PyPI — conversationally.