yapi-mcp

English | 中文

A zero-dependency YApi MCP server that exposes YApi's API-management capabilities to Claude Code and any MCP client.

Why this exists

The npm package @yogeliu/yapi-mcp-server has two defects that make it completely unusable:

1. Broken inputSchema serialization — it returns the Zod schema object itself as inputSchema. After JSON.stringify it becomes {"_def":...}, an invalid structure. MCP clients reject it with tools fetch failed, so none of the tools ever load.

2. Wrong interface-list strategy — YApi's /api/interface/list ignores catid on most versions and returns only the first page by default. The original package's "iterate categories" approach causes massive duplication and misses most interfaces; it also reads the wrong id field (_id).

This project is rewritten from scratch with zero runtime dependencies (only Node ≥18 built-in fetch), hand-written valid JSON Schemas, and project-level pagination with dedup — fixing all of the above.

Related MCP server: YAPI MCP Server

Tools

Install

Option 1: npx (recommended)

No install needed — use it directly in your MCP config:

{ "command": "npx", "args": ["-y", "@mail-tom/yapi-mcp"] }

Option 2: clone

git clone https://github.com/hizml/yapi-mcp.git

Point the config at the local file:

{ "command": "node", "args": ["/absolute/path/to/yapi-mcp/yapi-mcp.mjs"] }

Configuration

Two environment variables:

• YAPI_BASE_URL — YApi host, e.g. http://yapi.example.com

• YAPI_TOKEN — format projectId:tokenValue, from the YApi project "Settings → token"

Claude Code (~/.claude.json)

{
  "mcpServers": {
    "yapi": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@mail-tom/yapi-mcp"],
      "env": {
        "YAPI_BASE_URL": "http://your-yapi-host",
        "YAPI_TOKEN": "227:your_token_here"
      }
    }
  }
}

Full example: examples/claude-code-config.json.

Features

• Zero dependencies — pure Node ESM, only Node ≥18 built-in fetch

• Valid JSON Schema — every inputSchema is hand-written standard JSON Schema, so clients validate it fine

• Full pagination — project-level pagination + dedup, no missing or duplicate APIs

• Robust errors — param errors, timeouts, and YApi errcode all become isError messages; the process never crashes

• Debuggable — set DEBUG=1 to emit logs to stderr

Known limitations

• Currently single-token (single-project); for multiple projects, run multiple instances

• YApi's /api/interface/list total field is unreliable, so this tool stops paginating when a page returns fewer than the page size

License

MIT