TaskChampion MCP

TaskChampion MCP

适用于 Taskwarrior 3.x、TaskChampion 和 Timewarrior 的模型上下文协议服务。

献给留着胡子的 Unix 老手和键盘骑士：你们在终端里管理生活，现在也想让大模型搭把手。 🧔⌨️

最新版本： v1.0.4 — pip install taskchampion-mcp / uvx taskchampion-mcp

---

这是什么？

TaskChampion MCP 是一个模型上下文协议服务，可让大模型读取、创建、修改和管理你的 Taskwarrior 任务以及 Timewarrior 时间记录。它封装了 task 和 timew 命令行工具，并将它们作为结构化的 MCP 工具开放，供任何兼容的 AI 助手调用。

为什么要做这个？ 作者在家用服务器上自托管了 TaskChampion，希望能让大模型协助进行项目规划、任务拆解和时间跟踪，同时不放弃对任务数据库的控制权。

---

支持的平台

平台	传输方式	状态
Neovim（通过 Claude Code CLI）	stdio	v1.0.4
Cursor	stdio	v1.0.4
Windsurf	stdio	v1.0.4
VS Code（Copilot MCP）	stdio	v1.0.4
Claude Desktop	stdio	v1.0.4
HTTP/SSE 传输	HTTP/SSE	推迟至 v1.x

要求：

• Python 3.10+
• Taskwarrior 3.x（TaskChampion 同步）
• Timewarrior（可选，用于时间跟踪功能）

---

快速安装

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

# With pip
pip install taskchampion-mcp

然后配置 IDE 的 MCP 设置以使用：

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

针对各目标的安装指南：Claude Desktop | Windsurf | Cursor | Neovim

---

首次运行

在全新安装且没有 config.toml 的情况下，服务会以引导模式启动。所有工具都会显示在 tools/list 中，但在完成引导之前，操作类工具会返回结构化的 schema_unset 错误（ADR 19）。完成引导需要在 ~/.config/taskchampion-mcp/config.toml 中持久化两个键：

• role — 大模型可以执行的操作（CONTRIBUTOR / GENERATOR / MANAGER）
• schema 或 schema_path — 服务据以验证的任务架构

有三种方式可以完成：

1. 让大模型带你完成设置。 在不提供配置的情况下，将 IDE 连接到 MCP 服务并询问：“帮我设置 TaskChampion MCP。” 大模型会先调用 get_runtime_capabilities，看到 mode: "onboarding"，然后依次使用 get_initialization_status -> propose_initialization_options -> use_preset_schema（或 save_initial_schema）。成功后服务会自动重新加载——无需重启。
2. 运行 CLI 向导： ./dev.sh init（交互式）或 ./dev.sh init --preset gtd --role CONTRIBUTOR --non-interactive（脚本式）。
3. 手动编辑 config.toml——参见 quick_start.md。设置两个键后，从大模型调用 reload_configuration（或重启 IDE）。

这三种方式可以互换，并会生成相同的状态。根据谁来输入内容选择方式——决策指南见 initialization_flows.md。

---

权限级别

通过三个累积角色，控制 LLM 对任务的操作权限：

角色	可读取	可批注/修改	可创建	可完成/删除
CONTRIBUTOR	✅	✅	❌	❌
GENERATOR	✅	✅	✅	❌
MANAGER	✅	✅	✅	✅

在 ~/.config/taskchampion-mcp/config.toml 中设置角色：

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

---

任务架构

Taskwarrior 通过 UDA（用户自定义属性）支持自定义工作流。TaskChampion MCP 附带架构预设，可帮助 LLM 了解你的任务结构：

架构	说明
minimal	仅使用内置字段（优先级、项目、标签）
gtd	Getting Things Done（情境、精力、下一步行动）
scrum	基于 Sprint（故事点、Sprint ID、验收标准）
kanban	看板列、WIP 限制、服务类别
authors_custom_example	高级真实示例，包含生命周期阶段、假设驱动研究和 LLM 来源跟踪

首次运行时，MCP 会提示你选择架构，或根据现有任务自动生成架构。

---

安全性

此工具会让 LLM 间接访问你的任务管理 CLI。安全性不可忽视：

• 不执行 shell — 所有 CLI 调用均使用子进程参数列表，从不设置 shell=True
• 输入清理 — 所有 LLM 输入在传递给 CLI 前都会根据允许列表进行验证
• 速率限制 — 可配置每分钟/每小时上限，防止循环失控
• 审计日志 — 每项操作都会记录时间戳、工具、参数、结果和 result_code
• 带代码标签的封装 — 每个工具响应都包含稳定的 code 字段，便于机器安全地进行分支处理
• 试运行模式 — 每项破坏性操作都支持通过 dry_run 预览，且不会修改数据
• 确认模式 — 启用确认后，生命周期操作会使用明确的确认令牌
• 敏感字段脱敏 — 可配置从 LLM 响应中隐藏的字段

有关完整的安全性和可观测性设计，请参阅 ADR 9、ADR 13 和 ADR 14。

---

Taskwarrior 兼容性

版本	状态
Taskwarrior 3.x（TaskChampion）	✅ 完全支持
Taskwarrior 2.x（Taskserver/taskd）	⏳ 计划在未来版本中支持

我们专注于现代 Taskwarrior 3.x + TaskChampion 技术栈。Taskserver（taskd）已弃用，未来版本中仅提供有限支持。请参阅 ADR 8。

---

文档

文件夹 / 文件	内容
docs/adrs/	架构决策记录
docs/references/	上游工具参考（Taskd、TaskChampion、Timewarrior）
docs/manuals/quick_start.md	手动设置 config.toml
docs/manuals/configuration_reference.md	完整的配置键参考及优先级规则
docs/manuals/schema_authoring.md	编写自定义任务架构
docs/manuals/security_model.md	面向终端用户的安全控制
docs/manuals/initialization_flows.md	如何选择初始化方式（由大模型驱动、命令行或手动编辑）
docs/manuals/targets/	各 IDE 的安装指南（Claude Desktop、Windsurf、Cursor、Neovim）
docs/manuals/logrotate.md	审计日志轮转
docs/llm_context/	大模型 Agent 指南和已记录的假设
docs/CONTRIBUTING.md	如何参与贡献（分支、PR、版本控制）
docs/ROADMAP.md	功能路线图（v0.1.0 → v1.0.0）
docs/releases/v1.0.4.md	v1.0.2 发行说明和安装链接
docs/manuals/release_checklist.md	发布前的打标签检查清单
src/taskchampion_mcp/schemas/	随附的任务架构预设（TOML）
scripts/setup_remote.sh	一键远程主机引导脚本

---

故障排查

常见的首次运行和配置问题。详细操作指南请参阅 docs/manuals/quick_start.md 和 docs/manuals/initialization_flows.md。

现象	可能原因	解决方法
连接后工具返回 schema_unset 错误	~/.config/taskchampion-mcp/config.toml 缺少 role 或 schema/schema_path	在 [server] 下添加两项，然后调用 reload_configuration（或重启）。
Linux 上 Claude Desktop 安装完成，但 taskchampion 始终不出现	dev.sh 中 v0.3.0 之前版本的路径小写错误	更新到 v0.3.0 或更高版本。Linux：~/.config/Claude/ 中的 C 必须大写。
set_role("MANAGER") 返回 role_elevation_forbidden	禁止通过 MCP 自行提升权限（ADR 17）	手动编辑 config.toml，然后调用 reload_configuration。
MCP 服务启动时失败，并显示 Taskwarrior not found on PATH	未安装 task，或它不在 MCP 服务的 PATH 中	安装 Taskwarrior 3.x。如有需要，在配置中设置 task_binary。
Cowork / Claude Desktop：退出时安装 JSON 被覆盖	Claude Desktop 运行期间写入了配置	先退出 Claude Desktop，或使用 ./dev.sh reinstall claude -r。
工具列表中既没有引导工具，也没有贡献者工具	服务启动失败（检查标准错误输出）	在 shell 中运行 taskchampion-mcp-server 以查看错误。

对于更深层的故障情况，每个 MCP 工具都会返回稳定的 error_code 字段（ADR 14），并且每次调用都会记录审计日志（ADR 13），默认位置为 ~/.local/share/taskchampion-mcp/audit.log。

---

参与贡献

完整指南请参阅 docs/CONTRIBUTING.md。要点如下：

• 从 dev 分支创建分支，向 qa 提交 PR，从 qa 发布到 main
• 语义化版本控制（vMAJOR.MINOR.PATCH）
• 使用大模型辅助的贡献必须注明（参见 docs/llm_context/AGENTS.md）
• 所有未经验证的假设都必须记录在 docs/llm_context/assumptions_and_ideas.md 中

---

许可证

Apache License 2.0——可自由用于私人和商业用途。需通过 NOTICE 文件注明出处。

Copyright 2026 gabiup2

---

此项目在 Claude claude-sonnet-4-20250514 通过 Windsurf Cascade 提供的协助下启动。