Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@zentao-mcp 查一下指派给我的 Bug"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
这个服务把禅道 REST API 暴露为 MCP 工具，支持只读查询，以及经用户明确确认后解决 Bug。
zentao_list_bugs：分页查询 Bug。默认查询指派给当前 MCP 账号的 Bug；用户说“全部/所有 Bug”时传入 scope=all。
zentao_search_bugs：按标题关键词搜索 Bug，默认只搜索指派给当前 MCP 账号的 Bug。
zentao_get_bug：读取指定 Bug 的完整详情，并默认通过 REST API 下载描述中的截图，以 MCP 图片内容返回。
zentao_list_products：读取当前账号可见的产品列表，获得产品 Bug 查询所需的 productId。
zentao_resolve_bug：把 Bug 标记为 fixed，并自动指派回提 Bug 的人。该工具是写操作，必须传入 confirm=true。
解决 Bug 时默认使用主干 trunk 作为解决版本；如果团队按构建管理版本，请传入具体的构建 ID。工具会先读取
Bug 的创建人账号，再调用禅道 /bugs/{id}/resolve 接口，并显式把 assignedTo 设置为创建人。已达到目标状态的
Bug 不会重复写入，已关闭 Bug 会被拒绝修改。
读取 Bug 时默认返回最多 5 张截图，可通过 maxImages 调整为 1 到 10 张，或设置 includeImages=false
只读取文本详情。截图优先根据禅道的 file-read-<id> 地址或图片附件 ID 使用 /files/{id} 下载，不依赖浏览器
Cookie。单张截图限制为 5 MiB，单次调用的截图总量限制为 15 MiB；某张图片下载失败时仍会返回 Bug 详情，并在
imageSummary.failures 中说明原因。
禅道官方 v1 文档的产品 Bug 列表接口是 /products/{productId}/bugs。建议先调用
zentao_list_products，再把产品 ID 传给 zentao_list_bugs 或 zentao_search_bugs；当前实例也保留了
无产品 ID 的全局 /bugs 尝试，若该部署返回 404，工具会提示改用产品 ID。
Related MCP server: ZenTao MCP Server
服务启动后的第一次查询会使用账号密码调用禅道的 POST /api.php/v1/tokens 自动认证，并只在当前进程内
缓存临时凭据；遇到 401 时会自动重新认证。密码不会写入 MCP 响应或日志。
账号和密码属于敏感凭据，不要提交到 Git、聊天记录或共享配置文件。项目组成员应使用自己的禅道账号， 并确保账号至少拥有 Bug 查看权限。
调用示例：
{"name":"zentao_list_bugs","arguments":{"scope":"all","productId":51}}
{"name":"zentao_list_bugs","arguments":{"scope":"assigned_to_me","productId":51}}自然语言示例：
查产品 51 下我账号的 Bug
查指派给我的 Bug，关键词是“导出”
查产品 51 的全部 Bug
Bug 39766 已修复，解决版本是构建 12，备注“已修复并完成自测”，请标记已解决并指回提 Bug 的人首次安装离线包后运行：
zentao-mcp setup交互向导支持：
↑ / ↓：移动选项
空格：勾选或取消 Codex、Claude、Cursor 等客户端
回车：确认并进入下一步
Ctrl+C：安全取消，不写入后续配置
如果已经存在个人配置，setup 会先询问安装方式：
使用现有配置快速更新（推荐）：沿用地址、账号和密码，只检查并更新原来已配置的客户端。
重新运行完整配置向导：重新选择客户端，并可修改地址、账号和密码。
非交互模式检测到现有配置时默认快速更新；确实需要从环境变量重建配置时增加 --reconfigure。
普通终端不支持可靠的鼠标点击；需要鼠标操作时要另行提供桌面或网页安装器。
在本项目目录中开发时，先执行 pnpm install && pnpm build，再运行 pnpm setup。
向导会提示输入禅道地址、账号和密码，验证连接、保存个人配置，并自动写入检测到的 Codex、Claude
Desktop、Claude Code 和 Cursor 配置。配置完成后完全重启对应客户端即可。
当前公司的禅道地址使用 HTTP。HTTP 无法加密账号密码：交互向导会显示风险，并要求输入 y 后按回车继续。
优先建议为禅道启用 HTTPS；只有确认当前网络环境可信时才接受 HTTP 风险。
维护者生成离线安装包：
pnpm install
pnpm test
pnpm pack把生成的 tianjin-library-zentao-mcp-<版本>.tgz 放到 GitLab Release 或项目组共享目录。成员安装并运行向导：
npm install -g ./tianjin-library-zentao-mcp-0.4.0.tgz && zentao-mcp setup这是一条连续命令：安装成功后立即进入向导，同时避免使用容易卡住 CI/IDE 安装的 npm postinstall。
Windows PowerShell 使用：
npm install -g .\tianjin-library-zentao-mcp-0.4.0.tgz
if ($LASTEXITCODE -eq 0) { zentao-mcp setup }成员更新时安装新的 .tgz 后重新运行 zentao-mcp setup，选择默认的“使用现有配置快速更新”即可，不会再次
询问禅道地址、账号或密码。安装器会保留其他 MCP、备份发生变化的客户端配置并幂等更新 zentao 条目。
查看当前安装版本：
zentao-mcp -v同时支持 zentao-mcp --version、zentao-mcp -version 和 zentao-mcp version。
也可以直接使用 CLI：
node dist/cli.js setup
node dist/cli.js doctor --allow-insecure-http上述 doctor 示例针对当前 HTTP 禅道；HTTPS 地址无需风险参数。安装向导生成的客户端配置会根据地址自动附加
所需参数。直接用环境变量运行 doctor 或 serve 时，HTTP 地址同样必须显式传入
--allow-insecure-http。
非交互安装（账号密码从当前环境变量读取）：
ZENTAO_BASE_URL=http://106.75.28.240:31080/zentao \
ZENTAO_ACCOUNT=你的账号 ZENTAO_PASSWORD=你的密码 \
zentao-mcp setup --non-interactive --allow-insecure-http \
--clients codex,claude-desktop--allow-insecure-http 只表示明确接受 HTTP 明文传输风险；HTTPS 地址不需要该参数。非交互模式下，HTTP
地址缺少该参数会直接停止，且不会写入个人凭据或客户端配置。
如果只想跳过网络验证：
node dist/cli.js setup --skip-check --clients codex在独立项目目录中执行：
pnpm install
pnpm build
pnpm setup测试只使用 TypeScript 编译器和 Node.js 内置测试运行器，不需要额外的运行时转译器。
安装向导保存的个人配置默认位于：
macOS/Linux: ~/.config/zentao-mcp/profile.json
Windows: %APPDATA%\\zentao-mcp\\profile.json配置文件包含账号密码，安装向导会将其权限设置为仅当前用户可读。不要提交到 Git 或发送给其他人。
macOS/Linux：新建的配置目录使用 0700，配置文件使用 0600；已有目录权限保持不变。
Windows：配置保存在当前用户的 %APPDATA%，权限继承该用户目录的 ACL；请勿放入共享目录。
仅在源码开发场景下，可以复制 .env.example 为 .env.local。HTTPS 地址可通过 pnpm start:local 启动；
HTTP 地址使用 pnpm start:local -- --allow-insecure-http。
安装向导不会读取 .env.local；它使用交互输入，或在 --non-interactive 模式下读取当前进程环境变量。
通常无需手工配置。确有需要时，可复制 mcp-config.example.json，把 Node、CLI 和个人配置路径改为本机
绝对路径，再添加到客户端 MCP 配置。客户端配置只引用个人配置文件，绝不能直接包含账号密码。
安装器会保留其他 MCP，并在修改已有客户端配置前生成带时间戳的 .zentao-mcp.<时间>.bak 备份。若多客户端
配置中途失败，修正报错后可直接重跑 zentao-mcp setup；需要回退时，用输出中列出的备份覆盖对应配置文件。
pnpm test
pnpm type-check服务使用 Node.js 20 自带的 fetch，不依赖浏览器登录会话。禅道 API 错误只返回状态和通用提示，避免把
账号、密码或临时认证凭据泄露给模型。
只读读取指定禅道 Bug 的完整详情，并默认下载描述中的内嵌截图作为 MCP 图片内容返回。
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Bug ID | |
| maxImages | No | 最多返回的截图数量 | |
| includeImages | No | 是否下载并返回 Bug 描述中的截图 |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It explicitly discloses the read-only nature and the default behavior of downloading and returning embedded screenshots as MCP image content. This goes beyond mere 'get bug' and covers key behavioral traits, though it does not address error scenarios or response structure beyond images.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, well-structured sentence that front-loads the primary action and then specifies the default behavior. There is no redundancy or filler; every phrase earns its place, making it efficient and easy to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with three parameters (one required), a clear read-only purpose, and no output schema, the description covers the essential details. It does not explain return format for non-image data, but that is not mandated given the absence of an output schema. The description is sufficient for an agent to understand when and how to invoke it.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description adds minimal value beyond the schema: it mentions the default image-download behavior, which aligns with includeImages, but does not clarify parameter formats or provide additional context. The description's mention of returning images as MCP content is the only extra semantic insight.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action: read-only retrieval of a specific ZenTao bug's full details. It identifies the resource (bug) and the operation (get by ID), and the mention of default screenshot downloading adds specificity that distinguishes it from sibling list/search tools. The purpose is unambiguous and non-tautological.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for fetching a single bug's details as opposed to listing or searching bugs, which is clear from the wording. However, it does not explicitly state when not to use this tool or name alternatives, though sibling names provide that context. It offers clear context without explicit exclusions, warranting a 4.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
只读查询禅道 Bug 列表。默认查询指派给当前 MCP 账号的 Bug；用户明确说“全部/所有 Bug”时查询当前账号可见的全部 Bug。支持分页、产品、项目、执行、状态和标题关键词筛选。
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | 页码，从 1 开始 | |
| limit | No | 每页数量，最大 100 | |
| scope | No | 查询范围：默认 assigned_to_me（只查询指派给当前 MCP 账号的 Bug）；说“全部/所有 Bug”时使用 all | assigned_to_me |
| status | No | 状态，例如 active、resolved、closed | |
| keyword | No | Bug 标题关键词 | |
| productId | No | 产品 ID | |
| projectId | No | 项目 ID | |
| executionId | No | 执行 ID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description carries the full burden. It discloses the read-only nature upfront and the behavioral quirk that scope depends on user phrasing ('all' vs default). This goes beyond basic purpose and is helpful. It lacks details on error conditions or return format, but the core safety trait is disclosed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with the read-only verb, followed by scope logic and filter summary. No fluff; every sentence adds operational value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema and no annotations, the description provides essential context: default scope, condition for all scope, and supported filters. However, it omits return-behavior details (pagination total, ordering, possible errors), leaving some aspects to inference. It is adequate for a list operation but not exhaustive.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so each parameter already has a description. The description adds a filtered overview (pagination, product, project, execution, status, keyword) that maps to the schema but does not add semantics beyond a summary. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb-resource pair ('read-only query ZenTao Bug list') and adds behavioral specifics about default scope. It is distinguishable from zentao_get_bug and zentao_resolve_bug, though not explicitly contrasted with zentao_search_bugs, which limits differentiation from that sibling.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explains the default scope (assigned to current MCP account) and the trigger for broader scope ('all bugs'), which is useful. However, it does not explicitly route the agent to sibling tools such as zentao_get_bug for single-bug lookups or zentao_search_bugs for search-like queries, so exclusions are absent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
只读读取当前禅道账号可见的产品列表，用于获得查询产品 Bug 所需的 productId。
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It explicitly states 'read-only reads', disclosing the non-mutating nature of the operation. It also scopes the data to 'products visible to the current account', which is useful context. No further behavioral details are necessary for a simple list operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, information-dense sentence. It front-loads the read-only nature and immediately states the purpose, with no filler or repetition. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a parameterless, simple list tool with no output schema, this description is complete. It tells the agent exactly what it returns (the product list) and why it's needed (to obtain productId for bug queries). Nothing essential is missing for an agent to call it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so the description need not explain any parameter semantics. Per the baseline for zero parameters, a score of 4 is appropriate since the schema covers nothing and the description adds no unnecessary detail.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('read-only reads'), the resource ('product list'), and the purpose ('to obtain productId for bug queries'). It naturally distinguishes itself from sibling tools that focus on bugs, since this is the only product-listing tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use this tool: whenever you need a productId to query product bugs. While it doesn't explicitly mention alternatives or exclusions, the sibling tools are all bug-related, making the use case unambiguous. The context is clear enough for an agent to select it appropriately.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
写操作：将指定禅道 Bug 的解决方案设为 fixed（已解决），并自动指派回该 Bug 的创建人。只有用户明确要求执行状态变更时才调用。
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Bug ID | |
| comment | No | 可选的解决备注 | |
| confirm | Yes | 必须为 true，表示用户已明确确认执行此写操作 | |
| resolvedBuild | No | 解决版本的构建 ID；未指定时使用主干 trunk | trunk |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnly=false, destructiveHint=true, and idempotentHint=true. The description adds valuable behavioral specifics beyond annotations: the resolution is set to 'fixed' and the bug is automatically reassigned to its creator. It also reinforces the confirmation gating, but does not elaborate on destructive side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences carry all essential information: the write-operation nature, the exact resolution action, the automatic reassignment, and the invocation condition. Nothing is redundant or missing.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complete schema coverage, existing annotations, and simple parameter set, the description provides enough context for an agent to invoke the tool correctly. It lacks only clarification of the return shape, but no output schema exists and none is strictly required for invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so each parameter (id, comment, confirm, resolvedBuild) is already documented. The description adds no parameter-level detail beyond the schema, so the baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb and resource state: setting the bug's resolution to 'fixed' and reassigning it to the creator. It also frames itself as a write operation, clearly distinguishing it from the read-oriented sibling tools (get/list/search).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly states when to call the tool: only when the user explicitly requests a status change. It does not explicitly name alternatives or exclusions, but the read siblings are implicitly excluded by the 'write operation' framing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
只读按标题关键词搜索禅道 Bug。默认只搜索指派给当前 MCP 账号的 Bug；用户明确说“全部/所有 Bug”时搜索全部可见 Bug。
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | 页码，从 1 开始 | |
| limit | No | 每页数量，最大 100 | |
| scope | No | 查询范围：默认 assigned_to_me（只查询指派给当前 MCP 账号的 Bug）；说“全部/所有 Bug”时使用 all | assigned_to_me |
| keyword | Yes | 标题关键词 |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden and does disclose key behavior: the operation is read-only, scope defaults to assigned-to-me, and 'all' means all visible bugs. This is meaningful context, though it does not describe output shape or pagination behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences front-load the read-only nature and then state the default scope and the explicit 'all' trigger. Every sentence earns its place with no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given four documented parameters, no output schema, and no annotations, the description provides the essential invocation context: keyword search, read-only behavior, and scope rules. It is sufficient for correct selection and invocation, though a note on return format would make it fully complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description adds value beyond the schema by clarifying when to set scope to 'all' versus the default, and by tying the keyword parameter to title search semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific verb and resource: read-only search of Zen Tao bugs by title keyword. The keyword-based search scope distinguishes it from sibling tools like zentao_get_bug, zentao_list_bugs, and zentao_resolve_bug.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides clear context for when to use the tool: default searches only bugs assigned to the current MCP account, and 'all' scope only when the user explicitly says all bugs. It does not explicitly name alternatives or exclusion cases, so slightly below the top score.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.4.0zentao_get_bugzentao_list_bugszentao_list_productszentao_resolve_bugzentao_search_bugsScored across 5 tools
Most tools are clearly distinct, but zentao_list_bugs and zentao_search_bugs overlap significantly since list_bugs already supports title keyword filtering. The descriptions help clarify the default scopes, but an agent could still be uncertain which to call for a keyword search.
All tool names follow the same zentao_<verb>_<noun> snake_case pattern, making the set predictable and easy to navigate. There are no mixed conventions or vague generic verbs.
Five tools is a compact, focused set for a bug-centric ZenTao server. Each tool addresses a specific read or write need without unnecessary bloat.
The server covers listing, searching, reading, and resolving bugs, but misses common bug lifecycle operations like creating, updating, reopening, or closing bugs. It also lacks project/execution listing tools despite list_bugs filtering on those fields.
MCP server for Pentest-Tools.com: run scans, manage findings and reports via your preffered LLM.
Zotero MCP server for Claude and ChatGPT: search, citations, safe writes, PDF passages and pages.
Voice-powered bug reporting with 13 MCP tools. Record bugs by talking; let AI find and fix them.
Zero-setup MCP gateway securely connecting AI to your tools with authentication and workflows
