MCP 服务器

YApi MCP Server

Provides tools for AI assistants to list, search, and get details of YApi interfaces.

README

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`	仅类型检查，不生成文件