What can you do with this server?

This MCP server lets you authenticate with PingCode and query/manage projects, releases, work items, and work item states. * Log in via browser, log out, and check authentication status. * Retrieve work item details by identifier such as #12345, 12345, or LFY-123. * List accessible projects and list a project’s release versions. * Search work items, optionally limited to a specific project. * Get release-associated bugs, stories, or all work items. * Update a work item’s status by specifying the target state name. Note: The provided schema does not expose TestHub tools or bug field update tools mentioned in the README.

How do I use PingCode MCP Server?

1. Click on "Deploy Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@PingCode MCP Server show me the details for work item LFY-2527" 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.

PingCode MCP Server

by ratatatat1

Overview Schema Source Related Servers Discussions Admin

TypeScript

Local

PingCode MCP Server

PingCode MCP (Model Context Protocol) 服务器,让 AI 助手能够与 PingCode 项目管理系统交互,支持查询工作项、发布版本管理、更新状态和缺陷字段,以及浏览 TestHub 测试库、测试模块和测试用例详情。

✨ 功能特性

🔐 便捷登录 - 支持浏览器登录和飞书等第三方登录
🔍 工作项查询 - 通过编号快速查看工作项详情
📋 发布管理 - 查询发布版本关联的缺陷和需求
🔎 全文搜索 - 搜索项目中的工作项
📊 版本列表 - 列出项目的所有发布版本
✏️ 状态更新 - 更新工作项的状态
🐛 缺陷管理 - 更新缺陷的原因分析、解决方案和解决方法
🧪 测试管理 - 列出测试库、测试模块、测试用例并查看用例详情

Related MCP server: Zentao MCP Server

📦 安装

方式一：全局安装（推荐）

npm install -g pingcode-mcp

安装后需要安装 Chromium 浏览器（用于登录）:

npx playwright install chromium

方式二：使用 npx（无需安装）

npx pingcode-mcp

首次使用会自动下载依赖。

🚀 快速开始

1. 配置 MCP 客户端

在你的 MCP 客户端（如 Windsurf、Cursor、Claude Desktop、Codex）中添加 pingcode-mcp：

全局安装后的配置

编辑 ~/.cursor/mcp.json 或 ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "pingcode-mcp": {
      "command": "pingcode-mcp",
      "env": {
        "PINGCODE_DOMAIN": "your-company.pingcode.com"
      }
    }
  }
}

使用 npx 的配置

{
  "mcpServers": {
    "pingcode-mcp": {
      "command": "npx",
      "args": ["-y", "pingcode-mcp"],
      "env": {
        "PINGCODE_DOMAIN": "your-company.pingcode.com"
      }
    }
  }
}

注意: 建议显式配置 PINGCODE_DOMAIN，避免连接到错误的 PingCode 实例。

在 Claude Desktop 中使用

编辑 Claude Desktop 配置文件：

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\\Claude\\claude_desktop_config.json

加入以下配置：

{
  "mcpServers": {
    "pingcode-mcp": {
      "command": "npx",
      "args": ["-y", "pingcode-mcp"],
      "env": {
        "PINGCODE_DOMAIN": "your-company.pingcode.com"
      }
    }
  }
}

保存后重启 Claude Desktop，然后可以直接提问：

请帮我登录 PingCode

查看工作项 <项目标识>-123 的详情

查看测试用例 <项目标识>-123 的详情

在 Codex CLI 中使用

如果你已经安装了 Codex CLI，可以直接把 pingcode-mcp 加到 Codex 的 MCP 配置里。

推荐命令：

codex mcp add pingcode-mcp \
  --env PINGCODE_DOMAIN=your-company.pingcode.com \
  -- npx -y pingcode-mcp

如果你已经全局安装了 pingcode-mcp，也可以这样配置：

codex mcp add pingcode-mcp \
  --env PINGCODE_DOMAIN=your-company.pingcode.com \
  -- pingcode-mcp

配置完成后可用下面的命令检查：

codex mcp list

然后启动 Codex，在对话里直接使用：

请帮我登录 PingCode

列出 <project_id> 项目的所有发布版本

查看测试用例 <short_id> 的详情

2. 首次登录

重启 MCP 客户端后，让 AI 助手调用 login 工具:

请帮我登录 PingCode

会自动打开浏览器，完成授权后凭证会保存在 ~/.pingcode-mcp/credentials.json。

3. 开始使用

查看工作项 <项目标识>-123 的详情

列出 <project_id> 项目的所有发布版本

查询发布版本 <release_id> 的所有缺陷

列出所有测试库

打开 <library_id> 测试库逐层浏览模块和用例

查看测试用例 <项目标识>-123 的详情

🛠️ 可用工具

工具名称	说明	参数
`login`	打开浏览器进行登录	无
`logout`	退出登录，清除凭证	无
`check_auth`	检查登录状态	无
`get_work_item`	获取工作项详情	`identifier`: 工作项编号（如 `<project_id>-123`）
`list_projects`	列出所有可访问项目	无
`list_releases`	列出项目的发布版本	`project_id`: 项目标识（如 `<project_id>`）
`get_release_items`	获取版本关联的工作项	`release_id`: 版本ID`project_id`: 项目标识`item_type`: bug/story/all
`search_work_items`	搜索工作项	`query`: 搜索关键词`project_id`: 项目标识（可选）
`list_test_libraries`	列出所有可访问测试库（钻取入口）	无
`browse_test_module`	逐层浏览测试模块树：一次返回当前位置的【子模块 + 直属用例 + 面包屑 + 下一步建议】。模块行展示"用例数"（直属与子树合计相等时显示一个数，否则显示 `直属 X / 子树合计 Y`），根层额外给出"测试库累计用例数"	`library_id`: 测试库标识`suite_id`: 模块 ID（可选，不传 = 进入根；传 = 进入该模块）`page_index`: 直属用例页码（可选，默认 0）`page_size`: 直属用例每页数量（可选，默认 20）
`search_test_cases`	在指定测试库内全库关键词搜索测试用例（跳跃式补充）	`library_id`: 测试库标识`keyword`: 搜索关键词（必填）`page_index`: 页码（可选，默认 0）`page_size`: 每页数量（可选，默认 20）
`get_test_case`	获取测试用例详情	`test_case_id`: 测试用例短 ID（如 `<short_id>`）或展示编号（如 `<project_id>-123`）
`update_work_item_state`	更新工作项状态	`work_item_id`: 工作项编号`state_name`: 目标状态
`get_bug_field_options`	获取缺陷字段可选值	`work_item_id`: 缺陷工作项编号
`update_bug_fields`	更新缺陷的分析和解决方案	`work_item_id`: 工作项编号`reason`: 原因分析（可选）`solution`: 解决方案（可选）`jiejuefangfa`: 解决方法（可选）

🧪 TestHub 钻取式工作流

测试用例的定位采用"逐层钻取"模式，AI 会按下面的循环走，直到找到目标用例：

list_test_libraries          # 1. 选库
        ↓
browse_test_module(library)  # 2. 进入根，看顶层模块
        ↓
browse_test_module(library, suite_id)   # 3. 进入某个模块
        ↓                               #    - 有子模块就继续 browse 钻入
        ↓                               #    - 看到目标用例就跳到下一步
get_test_case(test_case_id)  # 4. 看用例详情（步骤、前置条件、版本等）

每一步返回的模块行都带"用例数"：

数字单显示 → 直属和子树合计相等（典型叶子模块）
直属 X / 子树合计 Y → 该模块自身挂了 X 条，整棵子树共 Y 条（X==0 表示纯目录壳子）

可以据此判断是否值得钻入；根层会先告诉你"测试库累计用例数"，方便横向比对。

如果已经知道关键词、不想逐层走，可以用 search_test_cases(library_id, keyword) 直接跳到结果列表。

💡 使用示例

查看工作项详情

查看 <项目标识>-123 的详情

查询发布版本的缺陷

从发布页面 URL 获取参数：

https://yourcompany.pingcode.com/pjm/projects/<project_id>/releases/<release_id>/workitems
                                                      ↑                ↑
                                                project_id        release_id

然后询问 AI:

查询项目 <project_id> 的发布版本 <release_id> 中的所有缺陷

搜索工作项

在某项目中搜索包含"登录"的工作项

列出测试库

列出所有测试库

浏览测试模块（钻取式）

进入测试库根，看顶层模块：

打开 <library_id> 测试库（不传 suite_id，进入根目录看顶层模块）

进入某个模块，看子模块和该模块下的直属用例：

进入 <library_id> 测试库的 <suite_id> 模块（钻入下一层）

AI 会基于返回的"下一步"提示循环调用 browse_test_module，直到找到目标用例编号。

关键词搜索测试用例（跳跃式）

在 <library_id> 测试库里搜包含"登录"的测试用例

查看测试用例详情

查看测试用例 <项目标识>-123 的详情

查看测试用例 <short_id> 的详情

更新工作项状态

把 <项目标识>-123 的状态改为已完成

更新缺陷分析字段

帮我更新 <项目标识>-123 的原因分析和解决方案

🔧 环境变量

变量名	说明	默认值
`PINGCODE_DOMAIN`	PingCode 域名	`your-company.pingcode.com`

🔨 本地开发

如果你想修改源码或为项目贡献代码：

# 克隆仓库
git clone https://github.com/ratatatat1/pingcode-mcp.git
cd pingcode-mcp

# 安装依赖
npm install

# 安装浏览器
npx playwright install chromium

# 开发模式（实时编译）
npm run dev

# 构建
npm run build

# 测试构建产物
npm start

在 MCP 客户端中使用本地开发版本

{
  "mcpServers": {
    "pingcode-mcp": {
      "command": "npx",
      "args": ["tsx", "/absolute/path/to/pingcode-mcp/src/index.ts"]
    }
  }
}

📂 项目结构

pingcode-mcp/
├── src/
│   ├── index.ts              # MCP 服务器入口
│   ├── api/
│   │   └── pingcode-client.ts # PingCode API 客户端
│   ├── tools/
│   │   ├── login.ts          # 登录相关工具
│   │   ├── work-items.ts     # 工作项相关工具
│   │   └── testhub.ts        # TestHub 测试管理工具
│   ├── types/
│   │   └── pingcode.ts       # TypeScript 类型定义
│   └── utils/
│       └── credentials.ts    # 凭证管理工具
├── dist/                     # 编译输出目录
├── package.json
├── tsconfig.json
└── README.md

🔒 隐私与安全

登录凭证仅保存在本地 ~/.pingcode-mcp/credentials.json
不会上传任何数据到第三方服务器
所有 API 请求直接发送到你的 PingCode 实例

❓ 常见问题

Q: 凭证过期了怎么办？ A: 重新调用 login 工具即可。

Q: 支持哪些 MCP 客户端？ A: 支持所有实现了 MCP 协议的客户端，包括 Windsurf、Cursor、Claude Desktop、Codex 等。

Q: 可以在 CI/CD 中使用吗？ A: 登录需要浏览器交互，不适合 CI/CD 环境。如需自动化，建议使用 PingCode API。

Q: get_test_case 应该传 <project_id>-123 还是 <short_id>？ A: 都支持。推荐优先使用展示编号（如 <project_id>-123），工具会自动解析为详情接口所需的短 ID。

📄 许可证

MIT License - 详见 LICENSE 文件

🤝 贡献

欢迎提交 Issue 和 Pull Request！

作者: ratat 关键词: mcp, pingcode, model-context-protocol, ai, release, bug-tracking, project-management

Available Tools

9 tools

check_authB

检查当前 PingCode 登录状态。

Inputs: no named parameters.

get_release_itemsC

获取某个发布版本关联的缺陷和需求列表。

Inputs: release_id (required), project_id (required), item_type.

get_work_itemB

通过 PingCode 工作项编号获取详情。支持格式：#12345、12345、LFY-123 等。

Inputs: identifier (required).

list_projectsB

列出用户可访问的所有项目。返回项目标识和名称列表。

Inputs: no named parameters.

list_releasesC

列出项目的所有发布版本。用户可以通过此工具查看版本名称和对应的 ID。

Inputs: project_id (required).

logoutA

退出 PingCode 登录，清除本地保存的凭证。

Inputs: no named parameters.

search_work_itemsC

搜索 PingCode 工作项。

Inputs: query (required), project_id.

update_work_item_stateC

更新工作项（缺陷/需求/任务）的状态。通过状态名称指定目标状态。

Inputs: work_item_id (required), state_name (required).

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

Deploy Server

Claude Code, inside the Godot 4 editorFlockbay puts an AI agent in the real Godot 4 editor: it writes GDScript, runs your game and fixes what breaks. Free, or bring your own Claude Code or Codex.flockbay.comAd

TDQS

B3.4/5.0

Scored 2026-04-18 07:20 across 9 tools

Disambiguation4/5

Most tools have distinct purposes, such as authentication (check_auth, login, logout), project/release management (list_projects, list_releases), and work item operations (get_work_item, search_work_items, update_work_item_state). However, get_release_items overlaps slightly with list_releases in dealing with releases, but its focus on associated items provides enough differentiation to avoid major confusion.

Naming Consistency4/5

The tools follow a consistent verb_noun pattern throughout, such as check_auth, get_work_item, and list_projects, which enhances readability. There are minor deviations like update_work_item_state using 'state' instead of a more specific noun, but overall the naming is predictable and well-structured.

Tool Count5/5

With 9 tools, the server is well-scoped for managing PingCode projects, releases, and work items. Each tool serves a clear purpose, such as authentication, listing, searching, and updating, without redundancy, making the count appropriate for the domain's core workflows.

Completeness4/5

The tool set covers key operations like authentication, project/release listing, and work item retrieval/search/updates, providing a solid foundation. A minor gap exists in the lack of tools for creating or deleting work items or releases, which agents might need to work around, but core lifecycle management is largely supported.

Maintenance

ActivityInactive

ResponsivenessLimited data

Resources

Related MCP Connectors

Orangescrum MCP Server
com.orangescrum
Manage Orangescrum projects, tasks, users, sprints, test cases, releases, and risks from AI tools.
Project Management Testing & QA Tools
13
https://mcp.orangescrum.com/mcp/partner
TrackingTimeC
io.github.TrackingTime
Connects AI assistants to TrackingTime for querying time entries, projects, tasks, customers, and team data using natural language.
Project Management Workplace & Productivity
1
https://mcp.trackingtime.co/mcp
Testiny Test ManagementA
io.testiny
Create and manage test cases, test runs and results in Testiny from your AI assistant.
Testing & QA Tools Project Management
152
https://app.testiny.io/api/v1/mcp-server
Loom
io.github.abhinand-adviciya
Manage Loom projects, tasks, bugs, defects, clients and phases from AI assistants
Project Management Testing & QA Tools
1
https://loom.adviciya.com/api/v1/mcp

Related MCP Servers

Tonle OpenProject MCP Server
Project Management Developer Tools
liratanak
A
license
Not graded
quality
D
maintenance
Enables AI assistants to interact with OpenProject's API v3 for comprehensive project management operations including work packages, projects, time tracking, users, and all other OpenProject features through natural language.
Updated 3 months ago (2026-08-03 05:27 UTC)
4
MIT
Zentao MCP Server
Project Management Testing & QA Tools Developer Tools
Tytt
A
license
Not graded
quality
D
maintenance
Enables AI assistants to manage Zentao bugs, requirements, and test cases through natural language interactions. It supports querying, creating, and updating various Zentao data entities including products, projects, and executions.
Updated 10 months ago (2026-01-23 02:56 UTC)
11 npm
12
MIT
Redmine MCP Server
Project Management Workplace & Productivity
Wint3rmute
A
license
Not graded
quality
D
maintenance
Enables AI applications to interact with Redmine project management systems for issue tracking, time logging, and project management through natural language.
Updated 9 months ago (2026-01-28 18:51 UTC)
15 npm
MIT
targetprocess-mcp-server
Project Management Testing & QA Tools
SerhiiMaksymiv
A
license
Not graded
quality
C
maintenance
Enables AI assistants to query, create, and manage Targetprocess entities like user stories, bugs, tasks, and features through natural language and structured tools.
Updated 2 months ago (2026-09-14 11:45 UTC)
128 npm
8
ISC

PingCode MCP Server

✨ 功能特性

📦 安装

方式一：全局安装（推荐）

方式二：使用 npx（无需安装）

🚀 快速开始

1. 配置 MCP 客户端

全局安装后的配置

使用 npx 的配置

在 Claude Desktop 中使用

在 Codex CLI 中使用

2. 首次登录

3. 开始使用

🛠️ 可用工具

🧪 TestHub 钻取式工作流

💡 使用示例

查看工作项详情

查询发布版本的缺陷

搜索工作项

列出测试库

浏览测试模块（钻取式）

关键词搜索测试用例（跳跃式）

查看测试用例详情

更新工作项状态

更新缺陷分析字段

🔧 环境变量

🔨 本地开发

在 MCP 客户端中使用本地开发版本

📂 项目结构

🔒 隐私与安全

❓ 常见问题

📄 许可证

🤝 贡献

Available Tools

Tool Schema Changelog

TDQS

Maintenance

Resources

Related MCP Connectors

Related MCP Servers

Tonle OpenProject MCP Server

Zentao MCP Server

Redmine MCP Server

targetprocess-mcp-server