AI导哈

任务管理集成工具

Taskwarrior MCP是一个完整的Taskwarrior集成工具，为Claude Code提供MCP服务器支持，包含11种工具、斜杠命令、专用代理和自动触发的技能，适用于任务管理、项目规划和进度跟踪。

  • by hnsstrk
  • Python
  • 本地部署
  • 1 星标
  • 更新于
在 GitHub 查看 hnsstrk/taskwarrior-mcp

使用说明

任务战士MCP

A完整 任务战士 整合 克劳德代码 --MCP服务器具有11个工具、斜线命令、专用代理和自动调用技能。

特性

  • 11 MCP工具 --创建、列出、修改、完成、删除、启动/停止任务、查询项目、标记和统计信息
  • 4击杀命令 -- /task-review, /task-plan, /task-inbox, /task-sync
  • 2名专业代理 -- task-manager （完全写入权限）和 task-reviewer （只读分析）
  • 汽车技能 --当上下文涉及任务、待办事项或截止日期时自动激活
  • 钩子 --写入操作后的视觉反馈
  • 壳体防喷 --对所有输入进行Pydantic验证， subprocess 随着 shell=False
  • 任务战士2.x和3.x --支持两个主要版本

先决条件

安装

1.克隆并安装MCP服务器

git clone https://github.com/hnsstrk/taskwarrior-mcp.git
cd taskwarrior-mcp
uv tool install -e ./mcp-server

这将安装 taskwarrior-mcp 作为一个可编辑的工具。代码更改立即生效。

2.在Claude Code中注册MCP服务器

claude mcp add --transport stdio --scope user taskwarrior \
  --env TW_MCP_LOG_LEVEL=WARNING \
  -- taskwarrior-mcp

3.加载插件

claude --plugin-dir /path/to/taskwarrior-mcp/plugin

为了实现持久访问，请在您的 ~/.zshrc 或 ~/.bashrc:

alias claude='claude --plugin-dir /path/to/taskwarrior-mcp/plugin'

快速开始

安装后，您可以直接通过Claude Code与Taskwarrior交互：

> What are my open tasks?
> Create a task "Review PR #42" with high priority, due end of week, in project Dev
> Mark task a1b2c3d4 as done
> /task-review

每当你提到任务、待办事项或截止日期时，该技能就会自动激活。您还可以对结构化工作流使用斜线命令。

配置

所有设置都是通过带有前缀的环境变量配置的 TW_MCP_:

变量 默认值 描述
TW_MCP_TASK_BINARY task Taskwarrior二进制文件的路径
TW_MCP_TASK_DATA -- 覆盖 rc.data.location
TW_MCP_TASKRC -- 通往替代方案的道路 .taskrc
TW_MCP_DEFAULT_LIMIT 50 任务列表的默认限制
TW_MCP_COMMAND_TIMEOUT 30 超时时间（秒）
TW_MCP_LOG_LEVEL INFO 日志级别（调试、信息、警告、错误）
TW_MCP_AUTO_SYNC false 自动 task sync 写入操作后

注册MCP服务器时设置环境变量：

claude mcp add --transport stdio --scope user taskwarrior \
  --env TW_MCP_LOG_LEVEL=WARNING \
  --env TW_MCP_TASK_DATA=/path/to/data \
  -- taskwarrior-mcp

可用工具

阅读工具

工具 说明
task_list 列出带有筛选器的任务（项目、标记、状态、自定义筛选器表达式）
task_get 按UUID检索单个任务（支持UUID前缀，至少8个字符）
task_projects 列出所有具有任务计数的项目
task_tags 列出所有标签
task_stats 返回任务战士统计数据（任务计数、速度等）

写入工具

工具 说明
task_add 添加具有可选项目、优先级、截止日期、标签、重复的新任务
task_modify 修改任务属性（添加/删除标签、更改优先级、截止日期等）
task_done 将任务标记为已完成
task_delete 永久删除任务
task_start 任务的开始时间跟踪（设置为活动）
task_stop 停止对活动任务的时间跟踪

筛选器语法

这 filter_expr 参数输入 task_list 支持本机Taskwarrior筛选器语法：

project:Work              # Filter by project
+urgent +OVERDUE          # Tags and virtual tags
due.before:eow            # Due before end of week
priority:H                # High priority
description.contains:meeting
status:pending            # Status (pending/completed/deleted/waiting)

日期格式

today, tomorrow, eow, eom, eoq, +2d, +1w, +3m, 2025-03-15

插件功能

斜杠命令

命令 描述
/task-review 日常任务审查工作流程
/task-plan [project] 每周计划会议
/task-inbox GTD收件箱处理
/task-sync 与服务器同步并显示状态

代理

代理 模型 访问 用例
task-manager 十四行诗 完全读/写 创建、修改和完成任务
task-reviewer Haiku 只读 项目概述、进度报告、工作量分析

技能

当对话上下文涉及任务、待办事项、截止日期、项目计划或审查时，Taskwarrior技能会自动激活。它为Claude提供了所有可用工具、过滤器语法、日期格式和最佳实践的完整知识。

钩子

后工具使用挂钩在写入操作后提供视觉确认(task_add, task_modify, task_done, task_delete, task_start, task_stop).

发展

所有命令都从运行 mcp-server/ 目录：

cd mcp-server
uv sync                                          # Install dependencies
uv run pytest                                    # Run all tests
uv run pytest tests/unit/                        # Unit tests only
uv run pytest tests/integration/                 # Integration tests (requires Taskwarrior)
uv run ruff check .                              # Lint
uv run mcp dev src/taskwarrior_mcp/server.py     # MCP Inspector at localhost:6274

更改后 pyproject.toml，重新安装（从repo根目录运行）：

uv tool install -e ./mcp-server --force

测试

  • 单元测试 嘲笑 subprocess.run 并验证 shell=False 在每次测试中
  • 集成测试 通过以下方式在隔离环境中使用真实的Taskwarrior实例 tmp_path
  • 异步测试 使用 pytest-asyncio 用于异步工具处理程序

插件测试

claude --plugin-dir plugin/

验证：MCP连接、斜线命令、代理可用性和自动技能激活。

建筑

此项目是一个包含两个组件的monorepo：

taskwarrior-mcp/
├── .claude-plugin/                 # Marketplace metadata
│   └── marketplace.json           # Claude Code plugin registry entry
├── mcp-server/                    # Python MCP server (PyPI: taskwarrior-mcp)
│   ├── src/taskwarrior_mcp/
│   │   ├── server.py              # FastMCP instance, 11 tool handlers
│   │   ├── taskwarrior.py         # CLI wrapper (subprocess, shell=False)
│   │   ├── models.py              # Pydantic v2 input validation
│   │   └── config.py              # pydantic-settings, env prefix TW_MCP_
│   └── tests/
│       ├── unit/                   # Mocked subprocess tests
│       └── integration/            # Real Taskwarrior tests
│
└── plugin/                         # Claude Code plugin
    ├── .claude-plugin/plugin.json  # Plugin manifest
    ├── .mcp.json                   # MCP server registration (uvx)
    ├── commands/                    # Slash commands
    ├── agents/                     # Specialized agents
    ├── skills/taskwarrior/         # Auto-invoked skill
    └── hooks/                      # Post-tool-use hooks

关键设计决策

  • 仅限UUID --整数任务ID在每次突变时都会发生变化；所有操作都使用UUID
  • shell=False 强制执行 --所有子进程调用都使用列表参数，从不执行shell
  • shlex.split() 用于过滤器 --正确处理筛选器表达式中的引号字符串
  • 退出代码1不是错误 --Taskwarrior返回1表示“没有匹配的任务”
  • 不 print() 在MCP服务器中 --stdio保留用于MCP协议；日志记录将转到stderr

贡献

欢迎捐款。请确保：

  1. 所有测试均通过(uv run pytest)
  2. 代码传递linting(uv run ruff check .)
  3. subprocess.run() 通话使用 shell=False 带列表参数
  4. 输入验证使用具有外壳注入防止功能的Pydantic模型

许可证

麻省理工学院

相关 MCP