TaskWarrior MCP Server

包装 TaskWarrior 命令行工具的 MCP 服务器。提供 22 个工具，用于任务管理、GTD 工作流和习惯追踪。

工具

基本任务操作

• add_task - 创建任务。支持 GTD 字段（context、energy、scheduled、wait、depends）和重复任务（recur）

• modify_task - 更新任务属性

• mark_task_done - 按 UUID 完成任务

• delete_task - 按 UUID 删除任务

• list_tasks - 使用过滤器查询任务（status、project、tags、dates）

• get_task_details - 按 UUID 获取单个任务

• start_task - 启动任务计时器

• stop_task - 停止任务计时器

• add_annotation - 向任务添加备注

• remove_annotation - 从任务移除备注

依赖

• add_dependency - 使任务 A 依赖任务 B

• remove_dependency - 移除依赖链接

GTD 工作流

• get_next_actions - 按 context、能量级别和可用时间筛选可执行任务

• process_inbox - 获取标记为 +inbox 的任务以进行处理

• get_waiting_for - 获取已委托/等待中的任务，按阻塞者/日期/项目分组

• get_blocked_tasks - 获取依赖未满足的任务

• get_project_status - 项目度量：下一步行动、完成百分比、陈旧度

• weekly_review - GTD 回顾数据：收件箱、已完成任务、停滞的项目、习惯

• get_someday_maybe - 获取标记为 +someday 的任务

批量操作

• create_project_tree - 一次调用创建包含多个任务和依赖的项目

• batch_modify_tasks - 对多个任务应用相同的修改

习惯/重复任务

• get_recurring_tasks - 获取重复任务及其完成统计、连续记录、频率

Related MCP server: TickTick MCP Server

环境要求

• Node.js 18+ 用于运行时

• Bun 1.3+ 用于开发工作流

• 已安装 TaskWarrior 且可作为 task 使用

安装

bun install
bun run build

运行

bun run start

或者在你的 MCP 客户端设置中配置：

{
  "mcpServers": {
    "taskwarrior": {
      "command": "node",
      "args": ["/path/to/taskwarrior-mcp/dist/index.js"]
    }
  }
}

Claude Desktop 捆绑包

此仓库现在包含适用于 Claude Desktop 的 MCPB 清单。

bun run mcpb:validate
bun run mcpb:pack

这将生成 dist/taskwarrior-mcp.mcpb。

该捆绑包打包了 MCP 服务器，但不会打包 TaskWarrior 本身。用户仍需要在宿主机上安装 task。对于非默认配置，MCPB 清单提供了可选的 TASK_BIN 和 TASKRC 设置。

响应格式

所有工具都返回 MCP 标准格式：

{
  "content": [
    {
      "type": "text",
      "text": "{\"tasks\": [...], \"metadata\": {...}, \"insights\": {...}}"
    }
  ]
}

GTD 工具返回包含以下内容的增强响应：

• tasks - 任务对象数组

• metadata - 计数（total、actionable、blocked、waiting、completed）

• insights - 摘要、建议、警告

• groups - 按项目/context/频率分组的任务

• relationships - 依赖链（如适用）

GTD 功能

任务字段

• scheduled - 开始工作的日期

• wait - 隐藏到指定日期（延迟）

• until - 任务在指定日期后过期

• context - GTD context（@home、@work、@phone）

• energy - 所需能量级别（H/M/L）

• depends - 此任务依赖的任务 UUID 数组

• parent - 父任务 UUID

• recur - 重复模式（daily、weekly、monthly 等）

• tags - 字母、数字、_ 和 -。写入标签时使用 Taskwarrior 的 tags: 属性，标签过滤器使用 tags.has:，因为 +tag 简写不接受连字符，而是会静默改写描述。

重复任务

设置 recur 和 due 来创建习惯：

{
  "description": "Take vitamins",
  "recur": "daily",
  "due": "today",
  "context": "@morning"
}

TaskWarrior 会创建一个模板任务（status:recurring），由它生成实例。使用 get_recurring_tasks 查看完成率和连续记录。

开发

bun run typecheck  # Type check source
bun run lint       # Lint source
bun run test       # Run integration tests against disposable Taskwarrior data
bun run build      # Build dist/
bun run check      # Run typecheck, lint, tests, and build