YAPI MCP Server

YAPI MCP 服务

一个用于与 YAPI 实例交互的模型上下文协议（MCP）服务。此服务可让大模型从你的 YAPI 项目中获取 API 文档详情。

功能

• 列出接口：获取项目中的所有接口分类和接口基本信息
• 获取接口详情：通过接口 ID 获取特定接口的详细信息
• 搜索接口：按标题或路径中的关键词搜索接口

工具

yapi_list_interfaces

列出特定 YAPI 项目中的所有接口分类及其包含的接口。

输入：

• project_token（可选）：YAPI 项目的令牌。如果已设置 YAPI_PROJECT_TOKEN 环境变量，则无需提供。

返回：包含各分类及简化接口对象（id、title、path、method、status）的 JSON 数组。

yapi_get_interface_details

通过接口 ID 获取特定 YAPI 接口的详细信息。

输入：

• project_token（可选）：YAPI 项目的令牌。如果已设置 YAPI_PROJECT_TOKEN 环境变量，则无需提供。
• interface_id（数字，必填）：特定 YAPI 接口的 ID。

返回：包含完整接口规范的 JSON 对象（请求／响应参数、请求头、请求体结构等）。

yapi_search_interfaces

按标题或路径中的关键词搜索接口。

输入：

• project_token（可选）：YAPI 项目的令牌。如果已设置 YAPI_PROJECT_TOKEN 环境变量，则无需提供。
• keyword（字符串，必填）：要搜索的关键词。

返回：包含匹配接口及其分类信息的 JSON 数组。

前置条件

1. 正在运行的 YAPI 实例
2. 有权访问你要交互的 YAPI 项目的令牌（可在 YAPI 项目的“Settings” -> “Tokens”中找到）
3. 已安装 Node.js 18+

环境变量

变量	必填	描述
YAPI_URL	是	YAPI 实例的基础 URL（例如，http://yapi.example.com）
YAPI_PROJECT_TOKEN	否	默认项目令牌。设置后，调用工具时可省略 project_token 参数

安装与配置

从源代码构建

git clone <this-repo>
cd yapi-mcp-server
npm install
npm run build

本地开发（npm link）

进行本地开发时，使用 npm link 创建全局符号链接：

cd yapi-mcp-server
npm link

这样即可全局使用 mcp-server-yapi 命令，无需硬编码路径。

Claude Desktop

添加到你的 claude_desktop_config.json：

macOS：~/Library/Application Support/Claude/claude_desktop_config.json Windows：%AppData%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "yapi": {
      "command": "mcp-server-yapi",
      "env": {
        "YAPI_URL": "<your-yapi-url>",
        "YAPI_PROJECT_TOKEN": "<your-project-token>"
      }
    }
  }
}

Claude Code（CLI）

使用 claude mcp 命令添加服务：

# Add to user config (available in all projects)
claude mcp add-json yapi -s user '{
  "type": "stdio",
  "command": "mcp-server-yapi",
  "env": {
    "YAPI_URL": "<your-yapi-url>",
    "YAPI_PROJECT_TOKEN": "<your-project-token>"
  }
}'

# Or add to project config (only for current project)
claude mcp add-json yapi -s project '{
  "type": "stdio",
  "command": "mcp-server-yapi",
  "env": {
    "YAPI_URL": "<your-yapi-url>",
    "YAPI_PROJECT_TOKEN": "<your-project-token>"
  }
}'

# Verify the configuration
claude mcp list
claude mcp get yapi

Cursor IDE

添加到你的 Cursor MCP 设置中：

macOS：~/.cursor/mcp.json Windows：%USERPROFILE%\.cursor\mcp.json

{
  "mcpServers": {
    "yapi": {
      "command": "mcp-server-yapi",
      "env": {
        "YAPI_URL": "<your-yapi-url>",
        "YAPI_PROJECT_TOKEN": "<your-project-token>"
      }
    }
  }
}

使用 npx（推荐用于分发）

如果已发布到 npm，可使用 npx 自动管理版本：

{
  "mcpServers": {
    "yapi": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-yapi"],
      "env": {
        "YAPI_URL": "<your-yapi-url>",
        "YAPI_PROJECT_TOKEN": "<your-project-token>"
      }
    }
  }
}

使用示例

配置完成后，你可以让 Claude：

• “列出我的 YAPI 项目中的所有 API”
• “获取 ID 为 12345 的接口详情”
• “搜索我的项目中与 ‘user’ 相关的 API”
• “显示所有 POST 端点”

故障排除

服务无法启动

• 确保已安装 Node.js 18+
• 确认 dist/index.js 的路径正确
• 检查是否已设置 YAPI_URL 且该地址可访问

身份验证错误

• 确认 YAPI_PROJECT_TOKEN 正确
• 检查 YAPI 项目设置中的令牌权限

网络错误

• 确保你的机器可以访问 YAPI 实例
• 如果使用内部网络，请检查防火墙设置

开发

# Install dependencies
npm install

# Build
npm run build

# Watch mode
npm run watch

# Run directly (requires env vars)
YAPI_URL=http://yapi.example.com npm start

许可证

MIT