yapi-mcp

YApi MCP Server —— 基于 Model Context Protocol（MCP）的 YApi 接口查询服务，通过 stdio 方式启动，可被 Trae、Codex 等 MCP 客户端直接集成。

功能概述

提供三个核心工具，帮助 AI 助手快速获取 YApi 上的接口信息：

工具名称	别名	说明
get_api_list	yapi_list_interfaces	获取项目完整接口列表
get_api_detail	yapi_get_interface_detail	根据接口 ID 获取详情
search_api	yapi_search_interfaces	按关键字搜索接口

旧名称和中文别名均可使用，功能完全相同。

环境要求

• Node.js >= 18
• 可访问的 YApi 服务

快速开始

1. 安装依赖并构建

npm install
npm run build

2. 配置环境变量

复制 .env.example 为 .env，填入实际值：

YAPI_BASE_URL=http://127.0.0.1:3000
YAPI_TOKEN=replace-with-your-yapi-token
YAPI_PROJECT_ID=1

变量名	必填	说明
YAPI_BASE_URL	是	YApi 服务根地址，如 http://127.0.0.1:3000，不要填项目页面地址
YAPI_TOKEN	是	YApi 项目级 Token，在项目设置中获取
YAPI_PROJECT_ID	否	默认项目 ID，建议配置，可避免每次调用时手动传入

3. 启动服务

npm start

或开发模式（无需构建，直接运行 TypeScript）：

npm run dev

客户端配置

Trae

在项目根目录创建 .trae/mcp.json：

{
  "mcpServers": {
    "yapi": {
      "command": "node",
      "args": ["${workspaceFolder}/dist/index.js"],
      "env": {
        "YAPI_BASE_URL": "http://127.0.0.1:3000",
        "YAPI_TOKEN": "replace-with-your-yapi-token",
        "YAPI_PROJECT_ID": "1",
        "START_MCP_TIMEOUT_MS": "60000",
        "RUN_MCP_TIMEOUT_MS": "60000"
      }
    }
  }
}

• 发布到npm上的使用方式

{
  "mcpServers": {
    "yapi": {
      "command": "npx",
      "args": ["-y", "mcp-yapi"],
      "env": {
        "YAPI_BASE_URL": "http://127.0.0.1:3000",
        "YAPI_TOKEN": "replace-with-your-yapi-token",
        "YAPI_PROJECT_ID": "1",
        "START_MCP_TIMEOUT_MS": "60000",
        "RUN_MCP_TIMEOUT_MS": "60000"
      }
    }
  }
}

也可将上述 JSON 粘贴到 Trae 的 MCP 手动配置中实现全局配置。

Codex

在 ~/.codex/config.toml 或项目级 .codex/config.toml 中添加：

[mcp_servers.yapi]
command = "node"
args = ["/path/to/yapi-mcp/dist/index.js"]
cwd = "/path/to/yapi-mcp"
startup_timeout_sec = 20
tool_timeout_sec = 60

[mcp_servers.yapi.env]
YAPI_BASE_URL = "http://127.0.0.1:3000"
YAPI_TOKEN = "replace-with-your-yapi-token"
YAPI_PROJECT_ID = "1"

请将 /path/to/yapi-mcp 替换为项目的实际路径。

CodeBuddy

在 CodeBuddy 的 MCP 配置中添加：

• 本地项目方式：

{
  "mcpServers": {
    "yapi": {
      "command": "node",
      "args": ["/path/to/mcp-yapi/dist/index.js"],
      "env": {
        "YAPI_BASE_URL": "http://127.0.0.1:3000",
        "YAPI_TOKEN": "replace-with-your-yapi-token",
        "YAPI_PROJECT_ID": "1"
      }
    }
  }
}

• npm 包方式：

{
  "mcpServers": {
    "yapi": {
      "command": "npx",
      "args": ["-y", "mcp-yapi"],
      "env": {
        "YAPI_BASE_URL": "http://127.0.0.1:3000",
        "YAPI_TOKEN": "replace-with-your-yapi-token",
        "YAPI_PROJECT_ID": "1"
      }
    }
  }
}

请将 /path/to/mcp-yapi 替换为项目的实际路径。

Cursor / VS Code + Cline 等

任何支持 stdio 模式的 MCP 客户端均可接入，核心配置项：

• command: node
• args: ["/path/to/mcp-yapi/dist/index.js"]
• env: 按上方环境变量表格配置

工具详情

get_api_list / yapi_list_interfaces

获取指定 YApi 项目的完整接口列表，自动分页获取全量数据。

参数：

参数	类型	必填	说明
projectId	number	否	项目 ID，不传则使用环境变量 YAPI_PROJECT_ID

返回示例：

{
  "errcode": 0,
  "data": {
    "project_id": 1,
    "total_pages": 1,
    "fetched_count": 25,
    "list": [
      {
        "_id": 101,
        "title": "用户登录",
        "path": "/api/user/login",
        "method": "POST"
      }
    ]
  }
}

get_api_detail / yapi_get_interface_detail

根据接口 ID 获取完整详情，包含请求参数、响应结构等信息。

参数：

参数	类型	必填	说明
id	number	是	接口 ID

返回示例：

{
  "errcode": 0,
  "data": {
    "_id": 101,
    "title": "用户登录",
    "path": "/api/user/login",
    "method": "POST",
    "req_body_type": "json",
    "req_body_other": "{ ... }",
    "res_body_type": "json",
    "res_body": "{ ... }"
  }
}

search_api / yapi_search_interfaces

根据关键字搜索接口，使用 YApi 内置搜索 API 并进行本地精确匹配过滤。

参数：

参数	类型	必填	说明
keyword	string	是	搜索关键字，匹配接口名称和路径
projectId	number	否	项目 ID，不传则使用环境变量 YAPI_PROJECT_ID

返回示例：

{
  "keyword": "login",
  "total": 2,
  "list": [
    {
      "id": 101,
      "title": "用户登录",
      "path": "/api/user/login",
      "method": "POST"
    },
    {
      "id": 102,
      "title": "登录日志",
      "path": "/api/user/loginLog",
      "method": "GET"
    }
  ]
}

项目结构

yapi-mcp/
├── index.ts                  # 入口文件（含 shebang）
├── src/
│   ├── index.ts              # 加载 MCP Server
│   ├── config/
│   │   └── yapi.ts           # 环境变量解析与校验
│   ├── server/
│   │   └── mcp.ts            # MCP Server 初始化与 stdio 连接
│   ├── services/
│   │   └── yapi.service.ts   # YApi API 请求层
│   ├── tools/
│   │   ├── index.ts          # 工具注册入口
│   │   ├── getApiList.ts      # 接口列表工具
│   │   ├── getApiDetail.ts    # 接口详情工具
│   │   └── searchApi.ts       # 接口搜索工具
│   └── types/
│       └── yapi.ts           # 共享类型定义
├── .env.example              # 环境变量示例
├── .trae/mcp.json.example    # Trae 配置示例
├── package.json
└── tsconfig.json

npm 脚本

命令	说明
npm run build	编译 TypeScript 到 dist/
npm start	运行编译后的 dist/index.js
npm run dev	开发模式，使用 tsx 直接运行 TypeScript
npm run check	仅类型检查，不生成文件

常见问题

启动时报错 "Missing required environment variable"

请确保已正确配置 YAPI_BASE_URL 和 YAPI_TOKEN 环境变量。可在 MCP 客户端配置的 env 字段中设置，或创建 .env 文件。

搜索结果不准确

search_api 使用 YApi 内置搜索 API 获取结果后，会进行本地二次过滤以确保关键字精确匹配。如果结果仍不理想，可尝试使用更具体的关键字。

接口列表不全

get_api_list 会自动分页获取全量数据（每页 100 条），无需手动翻页。如果数据量特别大，可能需要等待更长时间。

参考

• Trae 添加 MCP Server
• Trae MCP Server 安装链接
• Codex MCP 文档
• Model Context Protocol 规范