MCP server for reading YAPI API documentation
npm install @zhuxian/yapi-mcp-server一个 Model Context Protocol (MCP) 服务器,用于读取 YAPI 接口文档数据。让 LLM 客户端(Claude Code、Cursor 等)能够浏览和查看 YAPI 项目的接口信息。
- 查看项目信息、分类目录和接口列表
- 获取完整的接口详情,包括请求参数和响应 Schema
- 支持分页浏览,输出 Markdown 格式便于 LLM 理解
- 通过环境变量配置认证信息,安全可靠
- Node.js >= 18.0.0
``bash`
npx @zhuxian/yapi-mcp-server
`bash`
git clone
cd yapi-mcp
npm install
npm run build
服务器需要三个环境变量:
| 变量 | 说明 | 示例 |
|------|------|------|
| YAPI_BASE_URL | YAPI 实例地址 | https://yapi.example.com |YAPI_TOKEN
| | Cookie 中的 Token | eyJhbGciOiJIUzI1NiIs... |YAPI_UID
| | 用户 ID | 1828 |
> 如何获取 Token 和 UID:打开浏览器开发者工具 -> Application -> Cookies,找到 _yapi_token 和 _yapi_uid 的值。
方式一:使用命令添加
`bash添加到当前项目
claude mcp add yapi -e YAPI_BASE_URL=https://yapi.example.com -e YAPI_TOKEN=your_token -e YAPI_UID=1828 -- npx -y @zhuxian/yapi-mcp-server
方式二:手动配置
在
~/.claude/settings.json 中添加:`json
{
"mcpServers": {
"yapi": {
"command": "npx",
"args": ["-y", "@zhuxian/yapi-mcp-server"],
"env": {
"YAPI_BASE_URL": "https://yapi.example.com",
"YAPI_TOKEN": "your_token",
"YAPI_UID": "1828"
}
}
}
}
`$3
在项目根目录下的
.cursor/mcp.json 中添加:`json
{
"mcpServers": {
"yapi": {
"command": "npx",
"args": ["-y", "@zhuxian/yapi-mcp-server"],
"env": {
"YAPI_BASE_URL": "https://yapi.example.com",
"YAPI_TOKEN": "your_token",
"YAPI_UID": "1828"
}
}
}
}
`$3
`bash
YAPI_BASE_URL=https://yapi.example.com YAPI_TOKEN=xxx YAPI_UID=1828 npm run dev
`工具列表
$3
获取项目基本信息,包括名称、描述、基础路径和环境配置。
参数:
| 名称 | 类型 | 必填 | 说明 |
|------|------|------|------|
|
project_id | number | 是 | YAPI 项目 ID |---
$3
获取项目的接口分类列表(文件夹结构)。
参数:
| 名称 | 类型 | 必填 | 说明 |
|------|------|------|------|
|
project_id | number | 是 | YAPI 项目 ID |---
$3
分页获取项目下的接口列表。
参数:
| 名称 | 类型 | 必填 | 说明 |
|------|------|------|------|
|
project_id | number | 是 | YAPI 项目 ID |
| page | number | 否 | 页码(默认:1) |
| limit | number | 否 | 每页数量,最大 100(默认:20) |---
$3
按分类分页获取接口列表。
参数:
| 名称 | 类型 | 必填 | 说明 |
|------|------|------|------|
|
cat_id | number | 是 | 分类 ID(通过 yapi_get_cat_menu 获取) |
| page | number | 否 | 页码(默认:1) |
| limit | number | 否 | 每页数量,最大 100(默认:20) |---
$3
获取单个接口的完整详情,包括请求参数(Headers、Query、Body)、响应 Body Schema、描述和状态。
参数:
| 名称 | 类型 | 必填 | 说明 |
|------|------|------|------|
|
interface_id | number | 是 | 接口 ID |---
$3
获取项目下按分类分组的全部接口,返回完整的分类-接口层级结构。
> 注意:接口数量较多的项目可能返回较大的数据量。
参数:
| 名称 | 类型 | 必填 | 说明 |
|------|------|------|------|
|
project_id | number | 是 | YAPI 项目 ID |---
$3
解析 YAPI 页面 URL 并自动获取对应数据。
参数:
| 名称 | 类型 | 必填 | 说明 |
|------|------|------|------|
|
url | string | 是 | 完整的 YAPI 页面 URL |支持的 URL 格式:
-
/project/{id}/interface/api - 项目概览
- /project/{id}/interface/api/{interfaceId} - 接口详情
- /project/{id}/interface/api/cat_{catId} - 分类列表推荐使用流程
探索一个 YAPI 项目时的推荐调用顺序:
`
1. yapi_get_project → 了解项目概况
2. yapi_get_cat_menu → 查看分类结构
3. yapi_list_by_category → 浏览某个分类下的接口
4. yapi_get_interface → 获取具体接口的完整详情
`或者直接使用
yapi_get_by_url,传入 YAPI 页面 URL 即可。脚本命令
| 命令 | 说明 |
|------|------|
|
npm run build | 使用 SWC 编译 + 生成类型声明 |
| npm run watch | 监听模式编译 |
| npm run start | 运行编译后的服务器 |
| npm run dev | 使用 tsx 直接运行(无需编译) |
| npm run typecheck` | 仅类型检查,不输出文件 |MIT