yapi-mcp-bridge

v1.0.1

Published

17 days ago

通过 MCP 查询和维护 YApi 项目及接口

0High
0Medium
0Low

hua1

yapi mcp model-context-protocol

YApi MCP Bridge

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

快速开始：配置 MCP 客户端

推荐直接在 MCP 客户端中通过 npx 启动，无需提前克隆仓库或全局安装 npm 包。

使用前请确认：

已安装 Node.js 18 或更高版本，并且可以运行 npx。
当前电脑可以访问目标 YApi 服务。
已准备好 YAPI_HOST 和有相应项目权限的 YAPI_COOKIE。

YAPI_HOST 只填写协议和域名，不要包含 /api。登录 YApi 后，可以在浏览器开发者工具的 Network 面板中选择任意 YApi 请求，从 Request Headers 复制完整的 Cookie。

Cursor

全局配置文件为 ~/.cursor/mcp.json；只希望当前项目使用时，可以配置在项目目录的 .cursor/mcp.json：

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

保存配置后重启 Cursor，或者在 Customize > MCP 中重新加载并确认 yapi 已启用。参见 Cursor MCP 官方文档。

Codex

推荐使用命令添加：

codex mcp add \
  --env 'YAPI_HOST=https://yapi.example.com' \
  --env 'YAPI_COOKIE=_yapi_token=xxx;_yapi_uid=xx;' \
  yapi -- npx -y yapi-mcp-bridge@1

也可以直接编辑 ~/.codex/config.toml：

[mcp_servers.yapi]
command = "npx"
args = ["-y", "yapi-mcp-bridge@1"]
enabled = true

[mcp_servers.yapi.env]
YAPI_HOST = "https://yapi.example.com"
YAPI_COOKIE = "_yapi_token=xxx;_yapi_uid=xx;"

检查是否配置成功：

codex mcp get yapi

修改配置后重启 Codex。参见 Codex MCP 官方文档。

Claude Code

使用 Claude Code CLI 添加到用户级配置：

claude mcp add --scope user \
  -e 'YAPI_HOST=https://yapi.example.com' \
  -e 'YAPI_COOKIE=_yapi_token=xxx;_yapi_uid=xx;' \
  yapi -- npx -y yapi-mcp-bridge@1

检查是否配置成功：

claude mcp get yapi

重新启动 Claude Code 后即可使用。参见 Claude Code MCP 官方文档。

验证使用

客户端成功加载后，应能发现 9 个以 yapi_ 开头的工具。可以直接输入：

获取 YApi 项目 1922 的详情。

每位使用者都应配置自己的 YApi Cookie。Cookie 等同于登录凭据，不要提交到 Git、写入项目共享配置或分享给其他人。

功能

当前提供以下工具：

| 工具 | 用途 | 类型 | | --- | --- | --- | | 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 客户端误执行不可逆操作。

可选：全局安装

一般不需要全局安装；MCP 配置中的 npx 会自动下载并启动兼容的 1.x 版本。如果希望直接使用命令行，可以全局安装：

npm install -g yapi-mcp-bridge@1
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

使用

接入后，可以直接用自然语言让 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

执行 node --version，确认版本不低于 18。
执行 npx --version，确认 MCP 客户端可以找到 npx。
在终端执行 npx -y yapi-mcp-bridge@1，确认 Server 可以启动。
查看 MCP 客户端日志，确认 YAPI_HOST 和 YAPI_COOKIE 已传给 Server。

修改 `.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 安装目录。