YApi MCP

A stdio MCP server for YApi REST API and mock workflows. It lets Codex, Cursor, Claude Desktop, and other MCP clients query YApi interface docs, resolve mock URLs, and update mock responses without clicking through the YApi web UI.

How It Works

The MCP client starts this package as a child process over stdio. This package receives MCP tool calls, selects the configured project token, calls YApi's REST API, and returns structured results to the client.

YApi tokens are project-scoped. The recommended setup is:

1. User provides only the YApi base URL and one project token.
2. The onboarding agent calls YApi's read-only project API with that token.
3. The agent learns the project id and project name.
4. The agent writes project id + project name + token to the local MCP config.

After setup, users can usually give a YApi page link such as:

https://yapi.example.com/project/13/interface/api/1000

The server parses project id 13, matches it to the configured token, and then queries interface id 1000. If project id 13 is not configured, the tool returns an error telling the user to add that project's token first.

No YApi URL, token, or company-specific defaults are bundled in the npm package.

Requirements

• Node.js 20 or newer
• A YApi instance reachable from your machine
• One YApi project token for each YApi project you want to use

Codex Configuration

Add this to ~/.codex/config.toml after the onboarding step has discovered the project id and name:

[mcp_servers.yapi]
command = "npx"
args = ["-y", "@erlichmak/yapi-mcp"]

[mcp_servers.yapi.env]
YAPI_URL = "https://yapi.example.com"
YAPI_PROJECTS = "13:Surfease:replace-with-surfease-project-token"

Restart Codex or start a new Codex session after changing MCP config.

For multiple YApi projects, append more id:name:token entries:

[mcp_servers.yapi.env]
YAPI_URL = "https://yapi.example.com"
YAPI_PROJECTS = "13:Surfease:replace-with-surfease-token,42:Admin:replace-with-admin-token"

For normal usage, pass a YApi URL containing /project/<id>. The URL project id selects the matching configured token. When no URL is available, pass an explicit project value.

Single-project env is also supported, but it still requires the project id and name:

[mcp_servers.yapi.env]
YAPI_URL = "https://yapi.example.com"
YAPI_PROJECT_ID = "13"
YAPI_PROJECT_NAME = "Surfease"
YAPI_TOKEN = "replace-with-surfease-project-token"

Generic MCP Client Configuration

Many MCP clients use a JSON config like this:

{
  "mcpServers": {
    "yapi": {
      "command": "npx",
      "args": ["-y", "@erlichmak/yapi-mcp"],
      "env": {
        "YAPI_URL": "https://yapi.example.com",
        "YAPI_PROJECTS": "13:Surfease:replace-with-surfease-token,42:Admin:replace-with-admin-token"
      }
    }
  }
}

Environment Variables

• YAPI_URL: YApi base URL, for example https://yapi.example.com
• YAPI_PROJECTS: comma-separated project_id:project_name:token entries
• YAPI_PROJECT_ID: project id for single-project YAPI_TOKEN setup
• YAPI_PROJECT_NAME: project name for single-project YAPI_TOKEN setup
• YAPI_TOKEN: YApi project token for single-project setup
• YAPI_DEFAULT_LIMIT: optional, defaults to 20
• YAPI_MAX_LIMIT: optional, defaults to 100

Use one dedicated project token per YApi project. Avoid putting tokens in shared files, project files, or chat logs.

Tools

Read-only tools:

• yapi_list_projects
• yapi_parse_url
• yapi_get_project
• yapi_list_interface_menu
• yapi_list_interfaces
• yapi_search_interfaces
• yapi_get_interface
• yapi_get_mock_url
• yapi_prepare_mock

Write tools, protected by confirmation:

• yapi_update_mock
• yapi_save_interface
• yapi_import_data
• yapi_confirm_write

URL-Based Query Flow

For this user request:

查一下 https://yapi.example.com/project/13/interface/api/1000

The MCP client should:

1. Call yapi_parse_url or yapi_get_interface with the full URL.
2. Let the server parse project id 13 and interface id 1000.
3. Let the server match project id 13 against configured projects.
4. Show the user the matched project name and id before relying on the result.

Tool responses include a project object like:

{
  "project": {
    "key": "13",
    "id": 13,
    "name": "Surfease"
  }
}

If no configured token exists for the parsed project id, add that project's token through onboarding before querying or writing.

Mock Workflow

YApi's mock URL is derived from the YApi base URL, project id, and interface path:

https://yapi.example.com/mock/<project_id>/<interface_path>

For a request like:

给这个接口写一个成功 mock：https://yapi.example.com/project/13/interface/api/1000

An MCP client can:

1. Call yapi_get_interface with the URL.
2. Tell the user the matched project name and id.
3. Generate a JSON or MockJS-compatible response body from the interface schema.
4. Call yapi_update_mock with the same URL to create a pending write.
5. Call yapi_confirm_write only after the user confirms the exact write.
6. Call yapi_get_mock_url and give the mock URL to the app developer.

Write Confirmation

Write tools do not modify YApi immediately. These tools first return a pending write token:

• yapi_update_mock
• yapi_save_interface
• yapi_import_data

To execute the pending write, call yapi_confirm_write with the returned token and this exact confirmation text:

确认执行

The match is strict. Extra spaces, punctuation, or different text will not execute the write. Pending write tokens expire after 10 minutes.

Example Requests

Examples of user requests an MCP client can map to these tools:

列出已配置的 YApi 项目。
查一下 https://yapi.example.com/project/13/interface/api/1000。
给这个 YApi 链接生成 mock URL。
根据这个接口文档准备一个成功 mock，但先不要写入。
确认执行刚才的 mock 写入。
把这个 Swagger JSON 导入项目 13。

Security Notes

• Do not put YApi tokens into shared files, project files, or chat logs.
• Prefer project-scoped tokens over broad admin credentials.
• Review write operations before allowing an agent to update YApi data.
• Keep credentials in MCP client env config or a local secret manager.
• For internal YApi instances using self-signed certificates, prefer installing the company CA for Node.js. As a local-only fallback, an MCP config may set NODE_TLS_REJECT_UNAUTHORIZED = "0", but that disables TLS certificate verification for this process.