MCP 服务器

PingCode MCP Server

Enables AI assistants to query and manage PingCode project management data, including work items, releases, bugs, and requirements through natural language interactions.

README

PingCode MCP Server

PingCode MCP (Model Context Protocol) 服务器,让 AI 助手能够查询 PingCode 项目管理数据,包括工作项、发布版本、缺陷和需求等。

✨ 功能特性

🔐 便捷登录 - 支持浏览器登录和飞书等第三方登录
🔍 工作项查询 - 通过编号快速查看工作项详情
📋 发布管理 - 查询发布版本关联的缺陷和需求
🔎 全文搜索 - 搜索项目中的工作项
📊 版本列表 - 列出项目的所有发布版本

📦 安装

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

npm install -g pingcode-mcp

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

npx playwright install chromium

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

npx pingcode-mcp

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

🚀 快速开始

1. 配置 MCP 客户端

在你的 MCP 客户端（如 Windsurf、Cursor、Claude Desktop）配置文件中添加：

全局安装后的配置

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

{
  "mcpServers": {
    "pingcode-mcp": {
      "command": "pingcode-mcp"
    }
  }
}

使用 npx 的配置

{
  "mcpServers": {
    "pingcode-mcp": {
      "command": "npx",
      "args": ["-y", "pingcode-mcp"]
    }
  }
}

2. 首次登录

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

请帮我登录 PingCode

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

3. 开始使用

查看工作项 LFY-2527 的详情

列出优点云项目的所有发布版本

查询发布版本 QxednuAG 的所有缺陷

🛠️ 可用工具

工具名称	说明	参数
`login`	打开浏览器进行登录	无
`logout`	退出登录，清除凭证	无
`check_auth`	检查登录状态	无
`get_work_item`	获取工作项详情	`identifier`: 工作项编号（如 LFY-123）
`list_projects`	列出所有可访问项目	无
`list_releases`	列出项目的发布版本	`project_id`: 项目标识（如 LFY）
`get_release_items`	获取版本关联的工作项	`release_id`: 版本ID<br>`project_id`: 项目标识<br>`item_type`: bug/story/all
`search_work_items`	搜索工作项	`query`: 搜索关键词<br>`project_id`: 项目标识（可选）
`update_work_item_state`	更新工作项状态	`work_item_id`: 工作项编号<br>`state_name`: 目标状态

💡 使用示例

查看工作项详情

查看 LFY-2527 的详情

查询发布版本的缺陷

从发布页面 URL 获取参数：

https://yourcompany.pingcode.com/pjm/projects/LFY/releases/QxednuAG/workitems
                                                    ↑              ↑
                                              project_id      release_id

然后询问 AI:

查询项目 LFY 的发布版本 QxednuAG 中的所有缺陷

搜索工作项

在优点云项目中搜索包含"登录"的工作项

🔧 本地开发

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

# 克隆仓库
git clone https://github.com/yourusername/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     # 工作项相关工具
│   ├── types/
│   │   └── pingcode.ts       # TypeScript 类型定义
│   └── utils/
│       └── credentials.ts    # 凭证管理工具
├── dist/                     # 编译输出目录
├── package.json
├── tsconfig.json
└── README.md