Yapi-MCP Server

一个遵循 Model Context Protocol (MCP) 标准的 Node.js 服务，作为连接 AI 编程助手（如 Cursor, Claude Desktop）与 YApi 接口管理平台的桥梁。

功能特性

• 🔍 查询项目: 列出所有可访问的YApi项目
• 📋 获取分类: 获取项目下的接口分类和概要
• 🔎 搜索接口: 根据关键词、路径、请求方法搜索接口
• 📖 接口详情: 获取完整的接口文档信息
• ✏️ 保存接口: 创建新接口或更新现有接口
• ⚡ 智能缓存: 内置缓存机制，提升查询性能
• 🚀 多种模式: 支持stdio和SSE两种传输模式

安装

NPM安装（推荐）

# 全局安装
npm install -g yapi-mcp-server

# 或使用npx（无需安装）
npx yapi-mcp-server --help

本地开发

git clone https://github.com/yoge/yapi-mcp-server.git
cd yapi-mcp-server
npm install

快速开始

配置环境变量

创建 .env 文件：

# 必需配置
YAPI_BASE_URL=https://your-yapi-server.com
YAPI_TOKEN=123:your_token_123,456:your_token_456

# 可选配置
PORT=8080
CACHE_TTL=3600
LOG_LEVEL=info

开发模式

stdio 模式（用于MCP客户端集成）

# 使用环境变量（推荐）
npm run dev:stdio

# 或使用命令行参数
npm run dev:stdio -- --yapi-base-url=https://your-yapi.com --yapi-token=123:abc123,456:def456

SSE 模式（用于调试和开发）

# 使用环境变量（推荐）
npm run dev:sse

# 或使用命令行参数
npm run dev:sse -- --yapi-base-url=https://your-yapi.com --yapi-token=123:abc123 --port=8080

构建和运行

npm run build

# 使用环境变量（推荐）
npm run start:stdio

# 或使用命令行参数
npm run start:stdio -- --yapi-base-url=https://your-yapi.com --yapi-token=123:abc123

配置说明

命令行参数

| 参数 | 环境变量 | 描述 | 示例 | |------|----------|------|------| | --yapi-base-url | YAPI_BASE_URL | 必需. YApi服务地址 | https://yapi.example.com | | --yapi-token | YAPI_TOKEN | 必需. 项目Token | 123:abc123,456:def456 | | --stdio | - | 使用stdio传输模式 | - | | --sse | - | 使用SSE传输模式 | - | | --port | PORT | SSE服务器端口 | 8080 | | --cache-ttl | CACHE_TTL | 缓存TTL（秒） | 3600 | | --log-level | LOG_LEVEL | 日志级别 | debug |

Token配置格式

Token参数格式：projectId1:token1,projectId2:token2

例如：123:abcdef123456,456:ghijkl789012

MCP客户端集成

Claude Desktop

在 .model-context-protocol/mcp-servers.json 中添加：

{
  "mcpServers": {
    "yapi-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "yapi-mcp-server",
        "--stdio"
      ],
      "env": {
        "YAPI_BASE_URL": "https://your-yapi.com",
        "YAPI_TOKEN": "123:abc123,456:def456"
      }
    }
  }
}

Cursor

在项目中创建 .cursorrules 文件：

你可以使用以下YApi MCP工具来查询和管理接口文档：

1. yapi_list_projects - 列出所有项目
2. yapi_get_categories - 获取项目分类 
3. yapi_search_apis - 搜索接口
4. yapi_get_api_details - 获取接口详情
5. yapi_save_api - 创建/更新接口

请主动使用这些工具来帮助用户管理YApi接口文档。

可用工具

yapi_list_projects

列出当前配置Token可访问的所有项目。

输入: 无参数 输出: 项目列表

yapi_get_categories

获取指定项目下的所有接口分类。

输入:

• project_id: 项目ID

输出: 分类和接口概要列表

yapi_search_apis

搜索接口。

输入:

• query: 搜索关键词
• project_ids: 可选，指定项目ID列表
• method: 可选，请求方法过滤

输出: 匹配的接口列表

yapi_get_api_details

获取接口完整详情。

输入:

• api_id: 接口ID

输出: 接口详细信息

yapi_save_api

创建或更新接口。

输入: 接口详细信息 输出: 操作结果

开发

项目结构

src/
├── types/          # TypeScript类型定义
├── config/         # 配置管理
├── cache/          # 缓存层
├── services/       # 业务逻辑层
├── server/         # MCP服务器层
└── index.ts        # 入口文件

技术栈

• Node.js ^20.17.0
• TypeScript ^5.0.0
• @modelcontextprotocol/sdk ^1.6.0
• Axios - HTTP客户端
• Zod - Schema验证
• Pino - 日志记录
• Express - SSE服务器

许可证

MIT License