TAPD MCP Server
TAPD 是腾讯敏捷研发管理平台,覆盖需求、计划、研发、测试、发布研发全生命周期。通过 MCP (Model Context Protocol) 接入 Claude、Cursor 等 AI 助手,用自然语言管理需求、缺陷、任务和迭代。
Potencialize seu agente
O comando do próprio publicador. Não é um endpoint do PlugMCP.
Host a copy with our keys and logs.
npx -y @xihe-lab/[email protected]O Claude Code não tem link de instalação para um comando local. Copie o comando abaixo e execute-o em um terminal.
claude mcp add xihe-lab-tapd-mcp-server -- npx -y @xihe-lab/tapd-mcp-server@2.1.1Execute em um terminal.
{ "mcpServers": { "xihe-lab-tapd-mcp-server": { "command": "npx", "args": [ "-y", "@xihe-lab/[email protected]" ] } }}claude_desktop_config.json
URL remota ou um comando na sua máquina? Como as duas instalações diferem
Rodar no PlugMCP
A new server you create. It is not this listing's official endpoint. Use the publisher install when you want their URL and their credentials.
AbrirDo publicador
TAPD 是腾讯敏捷研发管理平台,覆盖需求、计划、研发、测试、发布研发全生命周期。通过 MCP (Model Context Protocol) 接入 Claude、Cursor 等 AI 助手,用自然语言管理需求、缺陷、任务和迭代。
MCP server for TAPD project management API, enabling AI assistants to manage stories, bugs, tasks, iterations and more via natural language
TAPD_ACCESS_TOKEN 为 TAPD 个人令牌:
注意替换以下参数(必填项标记为 必填,其余可选)。-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": ""
}
}
}
}
其他客户端配置方式:
~/Library/Application Support/Claude/claude_desktop_config.json(macOS).cursor/mcp.json 或 .vscode/mcp.json配置格式与上方相同。
WorkBuddy 采用标准 mcpServers 配置,支持两级配置文件:
操作入口:侧边栏 插件 → 右上角 MCP 服务器 → 配置 MCP,在可视化编辑器中粘贴与上方相同的 mcpServers 配置并保存(也可直接编辑上述路径的 JSON 文件)。
保存后检查 MCP Server 状态灯:🟢 连接成功;🔴 配置异常(依次检查 JSON 格式、npx 环境、凭证有效性)。
安全提示:
TAPD_ACCESS_TOKEN是调用凭证。使用项目级配置时,请将.workbuddy/加入.gitignore,避免提交到仓库。
配置完成后重启客户端,直接用自然语言与 AI 助手对话:
查看我的待办需求
创建一个高优先级缺陷:登录页面报 500 错误
当前迭代的进度怎么样
给任务 10001 录入 3 小时工时
注意:TAPD_API_USER/TAPD_API_PASSWORD(API 账号密码)与 TAPD_ACCESS_TOKEN(个人访问令牌)为两种调用方式,选一种即可。
2.1.0 起,server 默认只挂载工作台 8 域 85 工具 + 1 个 tapd_discover_tools 元工具(共 86 个),tools/list 上下文占用从约 46k token 降到约 17k token。其余工具不挂载即不可调用(可见性即权限边界),需要时用 discover 按需激活,无需重启。
{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 等
# 追加域(默认集之外):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,不影响启动)。
如果你依赖全量工具清单(如配置了工具白名单、或 AI 助手依赖少见的测试计划 / Wiki 工具),在 env 加一行 TAPD_TOOLSETS=all 即可恢复 2.0 行为;否则建议保持默认并让助手按需 discover。
共 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: "" }
2. 把返回的 markdown 拼进 description / comment 正文
或者一步到位:tapd_md_to_html(content="......", 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)——前端自动卡片化,无需任何转换。
comment/story/task/bug/wiki 的 create/update 工具支持 raw_html: true:description 原样透传(绕过 md→html 自动转换),适合已含 TAPD 原生富文本标记或需要确定性透传的场景。默认 false 走 md 管道(@昵称 / 附件引用自动转换)。
确认 Node.js >= 18 已安装,npx 可正常执行。修改配置后需重启客户端。
这是预期行为:默认只挂载工作台 8 域 85 工具(见工具集分级)。测试计划、Wiki、发布计划等工具需先 tapd_discover_tools({"toolset": "<id>"}) 激活;要完全恢复 2.0 全量挂载,设 TAPD_TOOLSETS=all。直接调用未激活工具会返回 "Tool not found"——这不是能力缺失,先 discover 即可。
按错误 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。
TAPD 的需求/缺陷/任务等实体长 ID 为 19-20 位数字(如 1139814312001001378),超出 JS 安全整数上限(Number.MAX_SAFE_INTEGER,16 位),以 JSON 数值形式传递会丢精度导致查询为空。所有长 ID 参数必须以字符串(带引号)传递。
所有工具的长 ID 参数描述均已包含引导提示;若传入安全整数范围内的数值(≤16 位,如短 ID)会自动转为字符串;超出安全范围的数值会返回明确错误提示,请按提示以字符串重传。
支持。设置 TAPD_API_USER 和 TAPD_API_PASSWORD 即可,与 Access Token 二选一。注意:TAPD 权限模型下 Basic Auth 仅支持读取类接口,写操作(create/update 等)会直接返回 TAPD_AUTH_METHOD_MISMATCH 指引错误;写场景请使用 Access Token。双凭证并存时 Access Token 优先。
MCP 客户端使用 npx 运行时会自动检查并下载最新版本。如需确保使用最新版本:
重新安装配置(会自动使用最新版本):
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"
修改配置文件中的版本号为 @latest 或删除版本锁定(WorkBuddy 的配置文件路径见「配置 MCP 客户端 → WorkBuddy」小节):
{
"mcpServers": {
"tapd": {
"command": "npx",
"args": ["-y", "@xihe-lab/tapd-mcp-server@latest"],
"env": { ... }
}
}
}
如果通过 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 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 领域模块组织)。
MCP server for TAPD project management API, enabling AI assistants to manage stories, bugs, tasks, iterations and more via natural language
{ "mcpServers": { "xihe-lab-tapd-mcp-server": { "command": "npx", "args": [ "-y", "@xihe-lab/[email protected]" ] } }}Ferramentas
Ainda não há lista de ferramentas. Servidores remotos recebem uma após a primeira verificação de saúde.
Perguntas frequentes
Copie nesta página a configuração stdio para Cursor, Claude Desktop, Claude Code ou VS Code. Ela usa a instalação do publicador, não um proxy do PlugMCP.
Este registro não lista nenhuma variável de ambiente obrigatória.
@xihe Lab/tapd roda localmente via stdio.
Última verificação: 2026-10-28. MCP server for TAPD project management API, enabling AI assistants to manage stories, bugs, tasks, iterations and more via natural language