TAPD MCP Server

TAPD 是腾讯敏捷研发管理平台，覆盖需求、计划、研发、测试、发布研发全生命周期。通过 MCP (Model Context Protocol) 接入 Claude、Cursor 等 AI 助手，用自然语言管理需求、缺陷、任务和迭代。

系统要求

• Node.js >= 18.0.0
• TAPD Access Token（推荐）或 TAPD API 账号密码

快速开始

1. 获取凭证

方式一：个人访问令牌（推荐）

TAPD_ACCESS_TOKEN 为 TAPD 个人令牌：

1. 登录 TAPD，进入 我的设置 → 个人访问令牌
2. 点击"创建个人访问令牌"
3. 令牌只显示一次，注意保存

方式二：API 账号密码（兼容）

• 未注册：前往 TAPD 开放平台 注册
• 已注册未授权 API：登录 TAPD，进入 公司管理 → API账号管理，复制 API 账号和 API 密钥

2. 配置 MCP 客户端

方式一：一键安装命令

注意替换以下参数（必填项标记为 必填，其余可选）。-s user 为用户级配置（所有项目生效），改为 -s project 则仅当前项目生效：

claude mcp add -s user tapd \
  --env TAPD_ACCESS_TOKEN=your_access_token \                        # 必填：个人访问令牌
  --env TAPD_DEFAULT_WORKSPACE_ID=your_workspace_id \                # 必填：默认项目 ID
  --env TAPD_NICK_NAME=your_nick_name \                              # 推荐：用户昵称，用于 owner/creator 默认值
  --env TAPD_DEFAULT_TASK_WORKITEM_TYPE_ID=your_task_type_id \       # 可选：默认 TASK 类型 ID，可通过 tapd_get_workitem_types 查询
  --env TAPD_DEFAULT_STORY_WORKITEM_TYPE_ID=your_story_type_id \     # 可选：默认 STORY 类型 ID
  -- npx -y "@xihe-lab/tapd-mcp-server@latest"

若忘记替换凭证，重新安装前需先卸载旧的配置：

claude mcp list
claude mcp remove tapd

方式二：手动配置

编辑 Claude Code 的配置文件（用户目录下 .claude.json）：

{
  "mcpServers": {
    "tapd": {
      "command": "npx",
      "args": ["-y", "@xihe-lab/tapd-mcp-server@latest"],
      "env": {
        "TAPD_ACCESS_TOKEN": "",
        "TAPD_API_USER": "",
        "TAPD_API_PASSWORD": "",
        "TAPD_API_BASE_URL": "https://api.tapd.cn",
        "TAPD_DEFAULT_WORKSPACE_ID": "",
        "TAPD_NICK_NAME": "",
        "TAPD_DEFAULT_STORY_WORKITEM_TYPE_ID": "",
        "TAPD_DEFAULT_TASK_WORKITEM_TYPE_ID": ""
      }
    }
  }
}

其他客户端配置方式：

• Claude Desktop：编辑 ~/Library/Application Support/Claude/claude_desktop_config.json（macOS）
• Cursor / VS Code：在项目根目录创建 .cursor/mcp.json 或 .vscode/mcp.json
• WorkBuddy（腾讯 CodeBuddy 办公客户端）：见下方专节

配置格式与上方相同。

WorkBuddy（腾讯 CodeBuddy 办公客户端）

WorkBuddy 采用标准 mcpServers 配置，支持两级配置文件：

| 级别 | 配置文件路径 | 适用场景 | |------|-------------|---------| | 用户级 | ~/.workbuddy/mcp.json | 配置一次，所有项目复用（推荐） | | 项目级 | <项目目录>/.workbuddy/mcp.json | 仅当前项目生效 |

操作入口：侧边栏 插件 → 右上角 MCP 服务器 → 配置 MCP，在可视化编辑器中粘贴与上方相同的 mcpServers 配置并保存（也可直接编辑上述路径的 JSON 文件）。

保存后检查 MCP Server 状态灯：🟢 连接成功；🔴 配置异常（依次检查 JSON 格式、npx 环境、凭证有效性）。

安全提示：TAPD_ACCESS_TOKEN 是调用凭证。使用项目级配置时，请将 .workbuddy/ 加入 .gitignore，避免提交到仓库。

3. 开始使用

配置完成后重启客户端，直接用自然语言与 AI 助手对话：

查看我的待办需求

创建一个高优先级缺陷：登录页面报 500 错误

当前迭代的进度怎么样

给任务 10001 录入 3 小时工时

环境变量

| 变量 | 必填 | 说明 | |------|------|------| | TAPD_ACCESS_TOKEN | 二选一 | 个人访问令牌（推荐） | | TAPD_API_USER + TAPD_API_PASSWORD | 二选一 | API 账号 + API 密钥 | | TAPD_API_BASE_URL | 否 | API 基础地址，默认 https://api.tapd.cn | | TAPD_DEFAULT_WORKSPACE_ID | 否 | 默认项目 ID，省去每次传 workspace_id | | TAPD_NICK_NAME | 否 | 用户昵称，作为 owner/creator 等参数的默认值 | | TAPD_DEFAULT_STORY_WORKITEM_TYPE_ID | 否 | 默认 STORY 工作项类型 ID | | TAPD_DEFAULT_TASK_WORKITEM_TYPE_ID | 否 | 默认 TASK 工作项类型 ID | | TAPD_TOOLSETS | 否 | 启动时在默认集之上追加挂载的工具集（逗号分隔域 id，大小写不敏感）；all = 全量挂载 216 工具（2.1.0 新增） | | TAPD_TOOLS | 否 | 工具白名单回补（逗号分隔，tapd_ 前缀可省略），与默认集并集生效（2.1.0 新增） | | TAPD_PERMISSION_MODE | 否 | 设为 readonly（大小写不敏感）进入只读档：全部写工具不挂载、不可调用（2.1.0 新增） |

注意：TAPD_API_USER/TAPD_API_PASSWORD（API 账号密码）与 TAPD_ACCESS_TOKEN（个人访问令牌）为两种调用方式，选一种即可。

工具集分级（2.1.0 新增）

2.1.0 起，server 默认只挂载工作台 8 域 85 工具 + 1 个 tapd_discover_tools 元工具（共 86 个），tools/list 上下文占用从约 46k token 降到约 17k token。其余工具不挂载即不可调用（可见性即权限边界），需要时用 discover 按需激活，无需重启。

默认集（启动即挂载）

| 工具集 id | 名称 | 工具数 | |---|---|---| | workspace | 工作空间 | 9 | | iteration | 迭代 | 7 | | user | 用户 | 4 | | story | 需求 | 28 | | bug | 缺陷 | 20 | | task | 任务 | 7 | | comment | 评论 | 4 | | utility | 工具箱（md↔html 富文本转换 / 批量详情 / 短ID转换） | 6 |

discover 元工具：按需激活

• 无参调用：返回全部 27 个工具集 {id, label, toolCount, active, isDefault} 及操作提示。
• {"toolset": "<id>"}：立即注册该域全部工具并触发 tools/list_changed（幂等，重复调用安全）。
• {"toolset": "all"}：一次性激活全部 216 工具。

AI 助手：tapd_discover_tools()
→ 发现 wiki 域（11 工具，active: false）
AI 助手：tapd_discover_tools({"toolset": "wiki"})
→ wiki 工具全部可见，随后可调用 tapd_get_wikis 等

环境变量配置（启动即挂载，免 discover）

# 追加域（默认集之外）：wiki + 发布计划
TAPD_TOOLSETS=wiki,release

# 完全恢复 2.0 全量挂载行为（推荐 2.0 老用户迁移期使用）
TAPD_TOOLSETS=all

# 只回补个别工具（与默认集并集生效，tapd_ 前缀可省略）
TAPD_TOOLS=tapd_create_release,get_wikis

# 只读档：全部写工具（含 tapd_change_workitem_type）不进入注册面
TAPD_PERMISSION_MODE=readonly

非法域 / 未知工具会在启动时经 MCP logging notification 告警并忽略（不写 stderr，不影响启动）。

从 2.0 升级

如果你依赖全量工具清单（如配置了工具白名单、或 AI 助手依赖少见的测试计划 / Wiki 工具），在 env 加一行 TAPD_TOOLSETS=all 即可恢复 2.0 行为；否则建议保持默认并让助手按需 discover。

支持的能力

| 模块 | 工具数 | 可用操作 | |------|--------|----------| | 需求 | 28 | 查询/创建/更新/复制/批量更新需求；需求分类管理；工作项类型转换；字段信息查询；模板管理；关联缺陷/测试用例；时间关系管理 | | 测试 | 28 | 测试用例 CRUD；测试用例分类；测试计划 CRUD；测试执行与结果；用例与计划关联管理 | | 缺陷 | 20 | 查询/创建/更新/复制/批量更新缺陷；缺陷关联管理；字段信息查询；模板管理；变更历史 | | 项目配置 | 21 | 模块/版本/特性/基线 CRUD；自定义字段配置；项目配置开关 | | Wiki | 11 | 查询/创建/更新 Wiki 页面；附件/DrawIO/权限/关注者/标签管理 | | 发布 | 11 | 发布计划 CRUD；发布评审创建与管理；评审依据管理；模板查询 | | 项目 | 9 | 项目信息查询；成员列表；子项目；文档；日历；自定义字段；第三方项目关联 | | 任务 | 7 | 查询/创建/更新/批量更新任务；任务变更历史 | | 迭代 | 7 | 查询/创建/更新迭代；迭代变更历史；锁定/解锁 | | 工作流 | 7 | 工作流定义查询；状态映射；节点信息；转换规则；首末步骤查询 | | 自定义字段 | 7 | 需求/缺陷/任务/测试用例/迭代自定义字段配置查询；字段信息查询 | | 轻量级项目 | 6 | 轻量级工作项查询/创建/更新；分类管理；变更历史 | | 附件 | 8 | 附件查询/下载；轻量级项目附件管理；外部文件挂接 | | 工时 | 5 | 工时记录查询/创建/更新/删除；工时统计 | | 评论 | 4 | 评论查询/创建/更新；评论数量统计 | | 用户 | 4 | 个人设置查询；角色列表；第三方用户映射；当前用户信息 | | 变更历史 | 4 | 需求/任务变更历史查询；变更数量统计 | | 看板 | 4 | 看板工作项创建/查询/更新；看板列查询 | | 关联关系 | 4 | 需求关联查询/添加/删除；关联缺陷查询 | | 工具类 | 6 | 短ID转长ID；批量获取需求/缺陷/任务详情；md↔html 富文本转换 | | 代码 | 3 | 代码提交记录添加/查询；提交对象详情 | | 轻量级项目空间 | 3 | 项目信息查询；成员列表；用户项目列表 | | 轻量级评论 | 3 | 评论查询/创建；评论数量统计 | | 报表 | 2 | 项目报表列表；状态流转时间统计 | | 项目集 | 2 | 项目集关联项目；项目集绑定实体 | | 图片 | 1 | 获取图片 URL | | 媒体素材 | 1 | 临时素材上传/获取 |

共 216 个工具，覆盖 27 个模块。2.1.0 起默认只挂载其中工作台 8 域 85 工具（见工具集分级），其余经 tapd_discover_tools 或 TAPD_TOOLSETS 激活。

富媒体协作

在评论、需求/缺陷/任务描述和 Wiki 里 @ 人、贴图、挂附件，四类用法如下（rc.2 新增）。

@ 提及

在 md 正文里直接写 @昵称（如 请 @徐昭 今天内确认），写管道会自动转成 TAPD at-who 提及标记（角标 + 通知）。@@ 表示字面 @（不触发提及）；代码段、链接 URL、邮箱里的 @ 不会被误伤。tapd_md_to_html 可传 workspace_id 校验昵称是否项目成员（成员接口不可用时自动跳过校验，服务端仍会智能识别）；关键通知场景建议同时填 cc 兜底。

图片

1. tapd_upload_image(image_path="./截图.png")
   → { image_src: "/tfl/pictures/202609/截图.png", markdown: "![image](/tfl/...)" }
2. 把返回的 markdown 拼进 description / comment 正文

或者一步到位：tapd_md_to_html(content="...![截图](./截图.png)...", upload_images=true)——扫描 md 里本地存在的图片路径，逐个上传图床并替换为 /tfl/ 远端路径（默认关闭的显式副作用，返回 uploaded_images 清单）。读侧用 tapd_get_image_url 可把 /tfl/ 路径换回临时访问 URL。

附件

1. tapd_upload_attachment(file_path="./设计稿.pdf", entity_type="story", entity_id="1139...")
   → 返回 embed_html（富文本锚点）与 embed_md（[📎 设计稿.pdf](attach:<ws>/<id>)）
2. 把 embed_md / embed_html 拼进评论或描述正文

tapd_md_to_html / 写管道会把 [📎 名称](attach:<ws>/<id>) 引用自动渲染成 TAPD 附件锚点卡片；读方向 tapd_html_to_md 把锚点还原为同名 md 引用。下载走 tapd_download_attachment（/attachments/down，无需额外授权）。第三方系统文件不传本体、只登记链接：tapd_attach_external_file。

内部链接（零成本）

正文里直接写 TAPD 工作项 URL 的 md 链接即可，如 [需求详情](https://www.tapd.cn/39814312/prong/stories/view/1139814312001001548)——前端自动卡片化，无需任何转换。

raw_html 直发通道

comment/story/task/bug/wiki 的 create/update 工具支持 raw_html: true：description 原样透传（绕过 md→html 自动转换），适合已含 TAPD 原生富文本标记或需要确定性透传的场景。默认 false 走 md 管道（@昵称 / 附件引用自动转换）。

常见问题

AI 助手没有识别到 TAPD 工具

确认 Node.js >= 18 已安装，npx 可正常执行。修改配置后需重启客户端。

升级 2.1.0 后工具清单变短了

这是预期行为：默认只挂载工作台 8 域 85 工具（见工具集分级）。测试计划、Wiki、发布计划等工具需先 tapd_discover_tools({"toolset": "<id>"}) 激活；要完全恢复 2.0 全量挂载，设 TAPD_TOOLSETS=all。直接调用未激活工具会返回 "Tool not found"——这不是能力缺失，先 discover 即可。

工具返回权限不足 (403)

按错误 JSON 的 code 分诊：

• TAPD_AUTH_METHOD_MISMATCH：当前凭证是 Basic Auth（仅支持读接口），写操作必须配置 TAPD_ACCESS_TOKEN（OAuth access token）。常见于「同时配了双凭证但 token 没生效」——检查变量名拼写与值非空（空串会回落 Basic）、配置作用域（项目级 .mcp.json 与用户级配置是两处）、改配置后必须重连 MCP/重启 CLI；重连后用 tapd_get_current_user 验证凭证身份
• TAPD_HTTP_403：读 tapdMessage 字段看 TAPD 原始原因——company does not match workspace 表示 token 所属企业与目标项目不匹配（或 workspace_id 传错）；其余在 TAPD 开放平台检查应用权限，确认已勾选所需 API 模块且对目标项目有授权

创建任务时提示权限不足

如果 OAuth Token 没有 tasks::create 权限，可以通过 tapd_create_story 工具传入 TASK 类型的 workitem_type_id 来创建任务（仅需 stories::create 权限）：

用 tapd_create_story 创建一个任务，workitem_type_id 设为 TASK 类型

可通过 tapd_get_workitem_types 查询项目中可用的 TASK 类型 ID。

调用工具报「ID 超出 JS 安全整数范围」或首次调用 ID 校验失败

TAPD 的需求/缺陷/任务等实体长 ID 为 19-20 位数字（如 1139814312001001378），超出 JS 安全整数上限（Number.MAX_SAFE_INTEGER，16 位），以 JSON 数值形式传递会丢精度导致查询为空。所有长 ID 参数必须以字符串（带引号）传递。

所有工具的长 ID 参数描述均已包含引导提示；若传入安全整数范围内的数值（≤16 位，如短 ID）会自动转为字符串；超出安全范围的数值会返回明确错误提示，请按提示以字符串重传。

支持 Basic Auth 吗

支持。设置 TAPD_API_USER 和 TAPD_API_PASSWORD 即可，与 Access Token 二选一。注意：TAPD 权限模型下 Basic Auth 仅支持读取类接口，写操作（create/update 等）会直接返回 TAPD_AUTH_METHOD_MISMATCH 指引错误；写场景请使用 Access Token。双凭证并存时 Access Token 优先。

更新

MCP 客户端使用 npx 运行时会自动检查并下载最新版本。如需确保使用最新版本：

Claude Code

重新安装配置（会自动使用最新版本）：

claude mcp remove tapd
claude mcp add -s user tapd \
  --env TAPD_ACCESS_TOKEN=your_access_token \
  --env TAPD_DEFAULT_WORKSPACE_ID=your_workspace_id \
  --env TAPD_NICK_NAME=your_nick_name \
  --env TAPD_DEFAULT_TASK_WORKITEM_TYPE_ID=your_task_type_id \
  --env TAPD_DEFAULT_STORY_WORKITEM_TYPE_ID=your_story_type_id \
  -- npx -y "@xihe-lab/tapd-mcp-server@latest"

Claude Desktop / Cursor

修改配置文件中的版本号为 @latest 或删除版本锁定（WorkBuddy 的配置文件路径见「配置 MCP 客户端 → WorkBuddy」小节）：

{
  "mcpServers": {
    "tapd": {
      "command": "npx",
      "args": ["-y", "@xihe-lab/tapd-mcp-server@latest"],
      "env": { ... }
    }
  }
}

npm 全局安装方式

如果通过 npm 全局安装使用：

# 查看当前安装版本
npm list -g @xihe-lab/tapd-mcp-server

# 更新到最新版本
npm update -g @xihe-lab/tapd-mcp-server

# 或指定版本安装
npm install -g @xihe-lab/[email protected]

更新后需重启 MCP 客户端。

npx 缓存清理

如果 npx 使用了旧版本缓存，可手动清理后重新运行：

# 清理 npx 缓存
npx clear-npx-cache

# 或手动删除缓存目录
rm -rf ~/.npm/_npx

查看版本信息

# 查看最新发布版本
npm view @xihe-lab/tapd-mcp-server version

# 查看所有已发布版本
npm view @xihe-lab/tapd-mcp-server versions

查看更新日志

查看 CHANGELOG.md 了解各版本的变更内容。

本地开发

@xihe-lab/tapd-mcp-server 以 npm 包分发，通过 npx -y @xihe-lab/tapd-mcp-server 运行（配置见上文）。本仓为 MCP 入口层（stdio server 接线），工具内核在同组织包 @xihe-lab/tapd-core 中演进——新增工具遵循其 ToolDef[] 模式（zod schema + handler，按 TAPD 领域模块组织）。

许可证

Apache-2.0