YApi MCP Bridge

A YApi Server based on the Model Context Protocol (MCP), allowing MCP-enabled AI clients to query, search, create, and update YApi interfaces.

Features

The following tools are currently available:

The Server does not provide delete tools, to prevent AI clients from accidentally performing irreversible operations.

Related MCP server: YAPI MCP PRO

Install with npm

No need to clone the repository; you can run it directly:

npx -y yapi-mcp-bridge

You can also install it globally:

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

After global installation, you can use the following command to view tool call statistics:

yapi-mcp-stats

Install from source

Requirements

• Node.js 18 or higher

• A YApi instance that is accessible

• A YApi Cookie with access permissions for the corresponding project

Running from source also requires pnpm 10 or higher. On macOS, you can use Homebrew to install Node.js and pnpm:

brew install node pnpm

Install dependencies

After entering the project directory, run:

pnpm install

Configure YApi

Copy the environment variable example:

cp .env.example .env

Edit .env:

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

Parameter descriptions:

• YAPI_HOST: The YApi service address. Only fill in the protocol and domain name; do not include /api.

• YAPI_COOKIE: The full Cookie string used when accessing YApi.

• YAPI_LOG_FILE: Optional log file path. The default is ~/.yapi-mcp/logs/yapi-mcp.log.

After logging in to YApi, you can open the Network panel in the browser developer tools, select any YApi request, and copy the Cookie from the Request Headers. The Cookie is equivalent to login credentials; do not commit it to Git or share it with others. This project ignores .env by default.

Start the Server

Run in the project root directory:

pnpm start

This is a stdio MCP Server. After starting it directly, there is no ordinary HTTP page and no interactive prompt is printed; it waits for the MCP client to communicate via standard input and output.

After a successful start, the Server outputs similar information through stderr, which does not pollute the stdout used for MCP communication:

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

Run the tests:

pnpm test

Connect to an MCP client

When using the npm package, add the following configuration to a client that supports stdio MCP Servers:

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

If starting from source, you can continue using the Node.js absolute path configuration:

{
  "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;"
  }
}

After modifying the configuration, restart or reload the MCP client. The client should discover 9 tools prefixed with yapi_.

Usage

After connecting, you can directly use natural language to have the AI client operate YApi.

Query projects and interfaces

获取 YApi 项目 1922 的详情。

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

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

yapi_get_interface by default only returns the following commonly used information:

• Interface ID, title, HTTP method, and path

• Interface description

• Path, Query, Header, and Body input parameters

• Response type and response content

When you need to troubleshoot YApi metadata or get the raw response, you can explicitly request full: true:

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

Create an interface category

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

Create an interface

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

Required parameters when creating an interface:

requestBody and responseBody need to be passed as strings. If the content is JSON or JSON Schema, it also needs to be serialized into a string first.

Update an interface

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

To update an interface, you only need to provide the interface ID and the fields to modify. Fields that are not provided are not sent to YApi.

Logs and call statistics

The Server writes logs to the following location by default:

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

Logs use the JSON Lines format, with one event per line. For example:

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

Tool logs only record the tool name, call status, and elapsed time. They do not record call parameters, interface content, Cookies, or other credentials.

When the number of appended log records exceeds 1000, the Server automatically deletes the oldest 300 records to prevent the log file from growing indefinitely.

View tool call frequency, success count, failure count, and average elapsed time:

# 全局安装
yapi-mcp-stats

# 从源码运行
pnpm stats

You can change the log location via YAPI_LOG_FILE. When using a relative path, it is resolved relative to the Server's startup directory; it is recommended to configure an absolute path in MCP clients.

FAQ

Returns "Please log in" or no permission

Check the following:

• Whether YAPI_COOKIE is complete and has not expired.

• Whether the user corresponding to the current Cookie has project access or edit permissions.

• Whether the MCP Server was restarted after changing the Cookie.

The client cannot find the Server

• Confirm that src/index.js in the MCP configuration uses an absolute path.

• Confirm that command points to an executable Node.js.

• Run pnpm test in the project directory to confirm that the dependencies and runtime environment are normal.

Changes to .env have no effect

.env is loaded from the Server's current working directory by default. When starting from the terminal, run pnpm start in the project root directory; when starting from an MCP client, it is recommended to explicitly pass YAPI_HOST and YAPI_COOKIE via the env in the configuration.

Project structure

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

Security notes

• Do not commit .env or YApi Cookies.

• Write tools will actually modify YApi data. Confirm the project ID, category ID, and interface ID before executing.

• It is recommended to use a YApi account with the smallest possible permission scope.

• Default logs are stored in the .yapi-mcp/logs/ directory under the user's home directory and are not written to the npm installation directory.