# TAPD MCP Server [Health: Active]

**Category:** 📋 Product Management  
**Repository:** https://github.com/sun-jingtao/tapd-mcp-server  
**GitHub Stars:** 0  
**npm Downloads (last month):** 791  
**Views:** 4  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/tapd-mcp-server-2

## Description
在 Cursor/Copilot 中查询、分析和回填 TAPD bug / 需求

## Tools
Capabilities this server exposes over MCP:

- **tapd_list_bugs** — 查询 TAPD bug 列表，默认查询当前登录用户负责的缺陷；传入 current_owner 可查询指定处理人名下的缺陷。传入 id 或 story_id 时不限处理人（story_id 返回该需求全部处理人名下的关联缺陷），可查到已转给他人的缺陷；显式传入 current_owner 时再按该处理人取交集。传入 workspace_id 时只查该项目；不传 workspace_id 时会聚合处理人参与的所有项目的缺陷（按 story_id 过滤时仍需具体项目）。支持按字段过滤：缺陷 ID、关联需求、标题、描述、状态、报告人、处理人、创建时间，以及优先级、严重程度、中文状态、标签、迭代、模块、版本/基线、发布计划、特性、缺陷类型/根源/解决方法/重现规律、各类人员（测试/开发/参与/抄送/修复/验证/审核/关闭人等）、环境（操作系统/平台）、测试方式/阶段/类型、排期/解决/关闭/修改/流转时间、自定义字段等，并可自定义排序（order）。返回的状态会附带项目工作流中文名（如「已解决（resolved）」）。【展示约定】向用户呈现结果时，请直接原样输出本工具返回的 Markdown 表格，完整保留「序号」「id」在内的所有列（其中「缺陷」列已是内嵌超链接的 Markdown 写法，请勿拆成裸 URL、改成纯文本或删除链接），不要裁剪列、改列名或将表格拆分重排；如需补充分类或小结，可在表格之外另起段落，但表格本身保持原样。
- **tapd_list_bug_changes** — 查询 TAPD bug 变更历史。bug_id、created 与 id 至少提供一个；可按变更人、变更字段过滤并自定义排序，include_add_bug=true 时返回创建缺陷的记录。状态变更会附带项目工作流中文名（如「接受/处理（in_progress） => 已解决（resolved）」）。
- **tapd_create_bug** — 在 TAPD 中创建一个已确认的新 bug，可选关联到指定需求，支持设置处理人、优先级、严重程度、模块、版本、迭代、排期、各类人员（测试/开发/参与人等）、工时、模板、自定义字段等。创建前建议先用 tapd_search_users 确认处理人的 nick；不传处理人则默认指派给当前登录用户。
- **tapd_get_bugs** — 批量获取多个 TAPD bug 的完整内容，包括描述、复现步骤、评论、附件、图片和视频等详细信息。状态会附带项目工作流中文名（如「已解决（resolved）」）
- **tapd_writeback** — 对 TAPD bug 执行一个或多个已确认操作：回填评论、更新标题、更新描述正文、更新状态、更新处理人，以及更新优先级、严重程度、模块、版本、迭代、排期、各类人员、工时、标签等标准字段和自定义字段。各功能相互独立且可自由组合，至少提供 comment、title、description、target_status、target_owners、标准字段或 custom_fields 之一。注意：各动作分多次请求提交、非事务，可能出现部分成功（结果会逐项标明成功/失败）。
- **tapd_upload_bug_attachment** — 把文件上传到指定缺陷的附件区（支持 png/jpg/mp4 等任意类型，单文件 ≤250MB）。文件内容用 base64 传入（Agent 通常无本地路径）。录屏、视频等应走此工具而非内嵌描述。上传后可用 tapd_get_bugs 在附件区核对。
- **tapd_upload_bug_image** — 上传图片到 TAPD 并返回 html_code（<img> 片段），用于嵌入缺陷描述。仅支持 png/gif/jpg/jpeg/bmp、单张 ≤5MB。本工具只上传图片、不修改描述：拿到 html_code 后需自行用 tapd_get_bugs 取原描述、拼接后再调 tapd_writeback 的 description（或直接用 tapd_append_bug_description_image 一步完成）。
- **tapd_append_bug_description_image** — 一步完成：上传图片 → 读取缺陷当前描述 → 把图片追加到描述末尾后整体回写。先读后写避免覆盖原有正文。仅支持 png/gif/jpg/jpeg/bmp、单张 ≤5MB。图片上传成功但描述写入失败时会明确提示（此时图片已上传，可改用 tapd_writeback 手动写回）。
- **tapd_list_stories** — 查询 TAPD 需求列表，默认查询当前登录用户负责的需求；传入 owner 可查询指定处理人名下的需求。传入 id 精确查询时不限处理人，可查到已转给他人的需求。传入 workspace_id 时只查该项目；不传 workspace_id 时会聚合处理人参与的所有项目的需求。支持按字段过滤：需求 ID、名称、描述、状态、创建人、处理人、创建时间，以及优先级、标签、版本、模块、迭代、分类、排期/修改/完成时间、父子需求、特性、技术风险、需求类别、发布计划、规模、测试重点、抄送/开发人、来源/类型、工时、自定义字段等，并可自定义排序（order）。返回的状态会附带项目工作流中文名（如「已实现（resolved）」）。【展示约定】向用户呈现结果时，请直接原样输出本工具返回的 Markdown 表格，完整保留「序号」「id」在内的所有列（其中「需求」列已是内嵌超链接的 Markdown 写法，请勿拆成裸 URL、改成纯文本或删除链接），不要裁剪列、改列名或将表格拆分重排；如需补充分类或小结，可在表格之外另起段落，但表格本身保持原样。
- **tapd_list_story_changes** — 查询 TAPD 需求变更历史和字段级变更详情。story_id、created 与 id 至少提供一个；可按变更人、变更字段、变更类型过滤并自定义排序；include_details=true 时返回 field_changes 变更详情。
- **tapd_create_story** — 在 TAPD 中创建一个已确认的新需求，支持设置处理人、优先级、迭代、父需求、标签、排期、工时、自定义字段等。创建前建议先用 tapd_search_users 确认处理人的 nick；不传处理人则默认指派给当前登录用户。
- **tapd_list_story_test_cases** — 查询指定 TAPD 需求直接关联的所有测试用例，支持按用例名称和状态在本地过滤
- **tapd_get_stories** — 批量获取多个 TAPD 需求的完整内容，包括描述、评论、附件、图片和视频等详细信息。状态会附带项目工作流中文名（如「已实现（resolved）」）
- **tapd_writeback_story** — 对 TAPD 需求执行一个或多个已确认操作：回填评论、更新描述正文、更新状态、更新处理人，以及更新标题、优先级、迭代、版本、工时、标签等标准字段和自定义字段。各功能相互独立且可自由组合，至少提供 comment、description、target_status、target_owners、标准字段或 custom_fields 之一。注意：各动作分多次请求提交、非事务，可能出现部分成功（结果会逐项标明成功/失败）。
- **tapd_list_workspaces** — 查询指定用户参与的所有 TAPD 项目（workspace），默认查询当前登录用户。默认过滤掉 category=organization 的公司/组织条目，只返回可用于查询缺陷和需求的具体项目。当用户名下存在多个 workspace_id 时，可先用此工具拿到全部项目 ID；tapd_list_bugs / tapd_list_stories 在不传 workspace_id 时即会跨这些项目聚合查询。
- **tapd_list_iterations** — 查询 TAPD 项目迭代列表，支持按迭代 ID、名称、状态过滤，以及描述、起止时间、迭代类别、计划应用、创建人、创建/修改/完成时间、锁定人、自定义字段等，并可自定义排序（order）与翻页；用于创建或更新需求时选择 iteration_id
- **tapd_search_users** — 按姓名、TAPD nick 或邮箱搜索项目成员。需要更新 bug 处理人前，应先用该工具确认目标处理人的 nick。
- **tapd_call_api** — 通用透传工具：直接调用 TAPD OpenAPI（https://api.tapd.cn）的任意 REST 接口，用于专用工具未覆盖的场景（任务、工时、测试计划、模块/版本配置、Wiki、看板等）。path 为官方文档（open.tapd.cn）中每个接口标注的 URL 路径，例如 GET /tasks（获取任务）、GET /stories/count（需求数量）、GET /modules（模块配置）、POST /timesheets（新增工时）。路径没有统一推导规则，不确定时应以官方文档为准，不要凭猜测拼路径——按 REST 直觉猜容易踩空，例如 Wiki 列表是 /wikis 而非 /wiki，/boards、/reports 也都不是有效路径。几乎所有接口都需要 workspace_id 参数。查询类接口默认返回 30 条，可用 page/limit 翻页。文件上传（multipart）不走本工具，请使用 tapd_upload_bug_attachment / tapd_upload_bug_image。注意：POST 写操作默认禁用，需在 MCP 配置 env 中设置 TAPD_ALLOW_RAW_WRITE=true，且每次调用需传 confirmed=true；优先使用专用写入工具（tapd_create_bug / tapd_writeback 等）。

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `npx` (confidence: high):

```json
"mcpServers": {
  "tapd-mcp-server": {
    "command": "npx",
    "args": ["-y","tapd-mcp-server"],
    "env": {
      "TAPD_ACCESS_TOKEN": ""
    }
  }
}
```

**Requires environment variables:** `TAPD_ACCESS_TOKEN` — the values above are empty placeholders; fill in real credentials before running (see the repository for what each one is for).

## Documentation

## What TAPD MCP Server MCP server does

TAPD MCP Server MCP server exposes TAPD project data and actions to an MCP-compatible coding assistant. It covers two main work item types: stories and bugs. Agents can search lists across participating workspaces, retrieve full records, inspect comments and attachments, and filter results by supported fields. Results can identify the owning project, which is useful when one person works across several TAPD projects.

The server also supports creating stories and bugs, updating their standard and custom fields, changing status or assignees, and adding comments or descriptions. Attachment tools handle bug files and inline images. Member search helps confirm the correct TAPD nick before changing an assignee.

## How it works

The client starts the package with `npx -y tapd-mcp-server` and passes `TAPD_ACCESS_TOKEN` through the MCP environment. The token is a TAPD personal access token. Read operations query TAPD without changing records. Write operations require explicit confirmation in the conversation, including creation, comments, status changes, and assignee updates.

For broader coverage, `tapd_call_api` can send requests to TAPD OpenAPI paths not covered by dedicated tools. POST requests through this passthrough remain disabled unless `TAPD_ALLOW_RAW_WRITE=true` is set, and they still require confirmation. The bundled prompts coordinate existing tools rather than adding separate write behavior. They can combine TAPD data with the current codebase when the client supports MCP prompts.

## Setup and configuration

Add the server to an MCP configuration file such as `.cursor/mcp.json` or `.vscode/mcp.json`:

```json
{
  "mcpServers": {
    "TAPD MCP": {
      "command": "npx",
      "args": ["-y", "tapd-mcp-server"],
      "env": {
        "TAPD_ACCESS_TOKEN": "your-token"
      }
    }
  }
}
```

`TAPD_ALLOW_RAW_WRITE` is optional and defaults to disabled. Set it to `true` only when raw POST access is needed. `TAPD_MCP_SENTRY_DSN` controls the default error reporting destination; setting it to an empty string disables the reporting described by the project.

## Tools and capabilities

TAPD MCP Server MCP server provides 18 tools grouped around these functions:

- List and retrieve stories, bug records, changes, and linked test cases.
- Create stories or bugs and write back fields such as status, priority, iteration, labels, workload, comments, and custom fields.
- List workspaces and iterations, then search users by TAPD member information.
- Upload bug attachments up to 250 MB, or inline images up to 5 MB; one tool appends an uploaded image to an existing description without replacing it.
- Call other TAPD OpenAPI endpoints through the guarded passthrough tool.

Three prompts are included: `tapd_prd_analysis`, `tapd_bug_fix_writeback`, and `tapd_test_doc`. They support engineering review before a PRD presentation, a confirmed bug-resolution write-back, and test-entry assessment followed by a generated `提测文档.md` file.

## Limitations and notes

The toolset does not automatically authorize changes: write actions require confirmation. Raw POST calls need both the environment flag and confirmation. The test-document prompt reads code and does not modify TAPD. Team dashboards and scheduled inspections are agent workflows that combine tools and client capabilities, not single built-in tools. Visualizations depend on the client, and the README specifically gives Cursor Canvas as an example.

_Full upstream README: https://allmcps.com/mcp/tapd-mcp-server-2/readme_