YApi MCP Bridge

一个基于 Model Context Protocol（MCP） 的 YApi Server，让支持 MCP 的 AI 客户端可以查询、搜索、创建和更新 YApi 接口。

功能

当前提供以下工具：

工具	用途	类型
yapi_get_project	获取项目详情	只读
yapi_get_interface	获取精简接口定义，可选返回原始全量数据	只读
yapi_list_categories	获取项目接口分类	只读
yapi_list_interfaces	分页获取项目接口，可按状态或标签筛选	只读
yapi_list_category_interfaces	分页获取分类下的接口	只读
yapi_search_interface	按标题、路径或 HTTP 方法搜索接口	只读
yapi_create_category	创建接口分类	写入
yapi_create_interface	创建接口	写入
yapi_update_interface	更新接口	写入

Server 不提供删除工具，避免 AI 客户端误执行不可逆操作。

使用 npm 安装

无需克隆仓库，可以直接运行：

npx -y yapi-mcp-bridge

也可以全局安装：

npm install -g yapi-mcp-bridge
yapi-mcp-bridge

全局安装后，可以使用下面的命令查看工具调用统计：

yapi-mcp-stats

从源码安装

环境要求

• Node.js 18 或更高版本
• 一个可以正常访问的 YApi 实例
• 有对应项目访问权限的 YApi Cookie

从源码运行还需要 pnpm 10 或更高版本。macOS 可以使用 Homebrew 安装 Node.js 和 pnpm：

brew install node pnpm

安装依赖

进入项目目录后执行：

pnpm install

配置 YApi

复制环境变量示例：

cp .env.example .env

编辑 .env：

YAPI_HOST=https://yapi.example.com
YAPI_COOKIE=_yapi_token=xxx;_yapi_uid=xx;

参数说明：

• YAPI_HOST：YApi 服务地址，只填写协议和域名，不要包含 /api。
• YAPI_COOKIE：访问 YApi 时使用的完整 Cookie 字符串。
• YAPI_LOG_FILE：可选的日志文件路径，默认是 ~/.yapi-mcp/logs/yapi-mcp.log。

可以在登录 YApi 后，通过浏览器开发者工具的 Network 面板选择任意 YApi 请求，从 Request Headers 中复制 Cookie。Cookie 等同于登录凭据，不要提交到 Git 或分享给其他人；本项目已经默认忽略 .env。

启动 Server

在项目根目录运行：

pnpm start

这是一个 stdio MCP Server。直接启动后没有普通的 HTTP 页面，也不会打印交互提示；它会等待 MCP 客户端通过标准输入输出进行通信。

启动成功后，Server 会通过 stderr 输出类似信息，不会污染用于 MCP 通信的 stdout：

[yapi-mcp] server started (stdio), tools=9, log=~/.yapi-mcp/logs/yapi-mcp.log

运行测试：

pnpm test

接入 MCP 客户端

使用 npm 包时，在支持 stdio MCP Server 的客户端中添加以下配置：

{
  "mcpServers": {
    "yapi": {
      "command": "npx",
      "args": [
        "-y",
        "yapi-mcp-bridge"
      ],
      "env": {
        "YAPI_HOST": "https://yapi.example.com",
        "YAPI_COOKIE": "_yapi_token=xxx;_yapi_uid=xx;"
      }
    }
  }
}

如果使用源码启动，可以继续使用 Node.js 绝对路径配置：

{
  "command": "node",
  "args": ["/absolute/path/to/yapi-mcp-server/src/index.js"],
  "env": {
    "YAPI_HOST": "https://yapi.example.com",
    "YAPI_COOKIE": "_yapi_token=xxx;_yapi_uid=xx;"
  }
}

修改配置后，重启或重新加载 MCP 客户端。客户端应能发现 9 个以 yapi_ 开头的工具。

使用

接入后，可以直接用自然语言让 AI 客户端操作 YApi。

查询项目与接口

获取 YApi 项目 1922 的详情。

列出 YApi 项目 1922 的所有接口分类。

在 YApi 项目 1922 中搜索路径包含 /order 的接口，并获取匹配接口的常用定义。

yapi_get_interface 默认只返回以下常用信息：

• 接口 ID、标题、HTTP 方法和路径
• 接口描述
• Path、Query、Header 和 Body 入参
• 响应类型和响应内容

需要排查 YApi 元数据或获取原始响应时，可以明确要求使用 full: true：

获取 YApi 接口 5001 的原始全量数据。

创建接口分类

在 YApi 项目 1922 中创建一个名为“订单管理”的接口分类。

创建接口

在 YApi 项目 1922、分类 3001 中创建接口：
标题为“创建订单”，方法为 POST，路径为 /orders，
请求体类型为 JSON，请求示例为 {"productId": 1001, "quantity": 2}，
响应示例为 {"id": 9001, "status": "created"}。

创建接口时的必填参数：

参数	说明
projectId	YApi 项目 ID
categoryId	接口分类 ID
title	接口标题
path	以 / 开头的接口路径
method	HTTP 方法，例如 GET、POST

requestBody 和 responseBody 需要传入字符串。如果内容是 JSON 或 JSON Schema，也需要先序列化成字符串。

更新接口

把 YApi 接口 5001 的标题修改为“查询订单详情”，状态修改为 done，并添加 order 标签。

更新接口只需要提供接口 ID 和需要修改的字段，未提供的字段不会发送给 YApi。

日志与调用统计

Server 默认把日志写入：

~/.yapi-mcp/logs/yapi-mcp.log

日志采用 JSON Lines 格式，每行一个事件。例如：

{"timestamp":"2026-08-21T08:00:00.000Z","event":"tool_call","tool":"yapi_get_interface","status":"success","durationMs":128}

工具日志只记录工具名、调用状态和耗时，不记录调用参数、接口内容、Cookie 或其他凭据。

日志追加后如果超过 1000 条记录，Server 会自动删除最早的 300 条，避免日志文件持续增长。

查看工具调用频次、成功数、失败数和平均耗时：

# 全局安装
yapi-mcp-stats

# 从源码运行
pnpm stats

通过 YAPI_LOG_FILE 可以修改日志位置。使用相对路径时，相对于 Server 的启动目录解析；MCP 客户端中建议配置绝对路径。

常见问题

返回“请登录”或没有权限

检查以下内容：

• YAPI_COOKIE 是否完整、是否已经过期。
• 当前 Cookie 对应的用户是否有项目访问或编辑权限。
• 修改 Cookie 后是否重新启动了 MCP Server。

客户端找不到 Server

• 确认 MCP 配置中的 src/index.js 使用绝对路径。
• 确认 command 指向可执行的 Node.js。
• 在项目目录执行 pnpm test，确认依赖和运行环境正常。

修改 .env 后没有生效

.env 默认从 Server 的当前工作目录加载。终端启动时请在项目根目录运行 pnpm start；MCP 客户端启动时建议通过配置中的 env 显式传入 YAPI_HOST 和 YAPI_COOKIE。

项目结构

src/
├── handlers/       # MCP 工具 handler 与 YApi 方法映射
├── tools/          # 工具定义、Zod 输入输出 Schema
├── index.js        # stdio Server 入口
├── server.js       # McpServer 注册
└── yapi.js         # YApi HTTP API 封装
test/               # 单元测试与 MCP 注册测试

安全提示

• 不要提交 .env 或 YApi Cookie。
• 写入工具会真实修改 YApi 数据，执行前应确认项目 ID、分类 ID 和接口 ID。
• 建议使用权限范围尽可能小的 YApi 账号。
• 默认日志保存在用户目录下的 .yapi-mcp/logs/，不会写入 npm 安装目录。