YAPI MCP Server

A Model Context Protocol (MCP) server for interacting with a YAPI instance. This server enables LLMs to retrieve API documentation details from your YAPI projects.

This release uses the MCP 2026-07-28 protocol over stdio. Legacy MCP initialization is intentionally not supported.

Features

• List Interfaces: Get all interface categories and basic interface info within a project
• List Project Interfaces: Page through a flat project interface list without loading the whole project
• List Category Interfaces: Page through interfaces for a category ID from a YAPI /cat_<id> URL
• Get Interface Details: Retrieve detailed information for a specific interface by its ID
• Get Interface Details Batch: Retrieve up to 10 interface details with bounded concurrency and per-ID errors
• Search Interfaces: Search for interfaces by keyword in titles or paths
• Runtime Response Validation: Reject malformed YAPI envelopes and tool payloads without exposing response values or request URLs

Tools

Every tool advertises an MCP output schema. Successful text content is the JSON serialization of the same validated structured result.

yapi_list_interfaces

Lists all interface categories and the interfaces within them for a specific YAPI project.

Input:

• project_id (optional): Numeric project ID. Not required if YAPI_PROJECT_ID is set.
• limit (optional, default 100): Maximum interfaces to return; allowed range is 1 to 500.

Returns: A structured object containing categories, including category_id, with simplified interface objects (id, category_id, title, path, method, status), return counts, and truncation metadata.

yapi_list_category_interfaces

Lists one page of interfaces for a category ID without loading every interface in the project.

Input:

• category_id (positive integer, required): The numeric ID from a YAPI /cat_<id> URL.
• page (optional, default 1): One-based page number.
• limit (optional, default 100): Page size; allowed range is 1 to 500.

Returns: Interface summaries plus returned, total, and total_pages pagination metadata.

yapi_list_project_interfaces

Lists exactly one server-paginated page of interfaces for a project.

Input:

• project_id (optional): Numeric project ID. Not required if YAPI_PROJECT_ID is set.
• page (optional, default 1): One-based page number.
• limit (optional, default 100): Page size; allowed range is 1 to 500.

Returns: A flat interface page with project_id, page, limit, returned, total, and total_pages metadata.

yapi_get_interface_details

Gets detailed information for a specific YAPI interface by its ID.

Input:

• project_id (optional): Numeric project ID. Not required if YAPI_PROJECT_ID is set.
• interface_id (number, required): The ID of the specific YAPI interface.

Returns: A structured object whose interface field contains the full interface specification (request/response parameters, headers, body schemas, etc.).

yapi_get_interface_details_batch

Gets details for a bounded set of known interface IDs while preserving input order. Requests run with a fixed concurrency limit of 3, and one failed ID does not discard successful entries.

Input:

• project_id (optional): Numeric project ID. Not required if YAPI_PROJECT_ID is set.
• interface_ids (array, required): Between 1 and 10 unique positive integer interface IDs.

Returns: A structured object with ordered per-ID results, requested, succeeded, and failed counts. Each result contains either success: true with interface, or success: false with a credential-safe error.

yapi_search_interfaces

Searches for interfaces by keyword in their titles or paths using bounded server-paginated scanning.

Input:

• project_id (optional): Numeric project ID. Not required if YAPI_PROJECT_ID is set.
• keyword (string, required): The keyword to search for.
• limit (optional, default 100): Maximum matches to return; allowed range is 1 to 500.
• max_scan_pages (optional, default 10): Maximum YAPI pages to scan; allowed range is 1 to 100.

Returns: Matching interfaces (including category_id when supplied by YAPI) plus pages_scanned, interfaces_scanned, project pagination totals, and truncation metadata. total is the number of matches found in the scanned pages. truncated_reason is match_limit, max_scan_pages, or null after a complete scan.

Prerequisites

1. A running YAPI instance
2. Access to the project token(s) for the YAPI projects you want to interact with (found in YAPI project "Settings" -> "Tokens")
3. Node.js 22+ installed

Environment Variables

Variable	Required	Description
YAPI_URL	Yes	Base URL of your YAPI instance (e.g., http://yapi.example.com)
YAPI_PROJECT_TOKEN	Yes	Project credential. It is read only from the process environment and never accepted as tool input
YAPI_PROJECT_ID	No	Default numeric project ID. Tool calls may override it with project_id
YAPI_REQUEST_TIMEOUT_MS	No	HTTP timeout in milliseconds (100-300000, default 10000)

Installation & Configuration

Build from Source

git clone <this-repo>
cd yapi-mcp-server
npm install
npm run build

Local Development (npm link)

For local development, use npm link to create a global symlink:

cd yapi-mcp-server
npm link

This makes mcp-server-yapi command available globally, avoiding hardcoded paths.

Claude Desktop

Add to your claude_desktop_config.json:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %AppData%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "yapi": {
      "command": "mcp-server-yapi",
      "env": {
        "YAPI_URL": "<your-yapi-url>",
        "YAPI_PROJECT_TOKEN": "<your-project-token>"
      }
    }
  }
}

Claude Code (CLI)

Use the claude mcp command to add the server:

# Add to user config (available in all projects)
claude mcp add-json yapi -s user '{
  "type": "stdio",
  "command": "mcp-server-yapi",
  "env": {
    "YAPI_URL": "<your-yapi-url>",
    "YAPI_PROJECT_TOKEN": "<your-project-token>"
  }
}'

# Or add to project config (only for current project)
claude mcp add-json yapi -s project '{
  "type": "stdio",
  "command": "mcp-server-yapi",
  "env": {
    "YAPI_URL": "<your-yapi-url>",
    "YAPI_PROJECT_TOKEN": "<your-project-token>"
  }
}'

# Verify the configuration
claude mcp list
claude mcp get yapi

Cursor IDE

Add to your Cursor MCP settings:

macOS: ~/.cursor/mcp.json Windows: %USERPROFILE%\.cursor\mcp.json

{
  "mcpServers": {
    "yapi": {
      "command": "mcp-server-yapi",
      "env": {
        "YAPI_URL": "<your-yapi-url>",
        "YAPI_PROJECT_TOKEN": "<your-project-token>"
      }
    }
  }
}

Using npx (Recommended for distribution)

Version 0.8.0 requires an MCP 2026-07-28 client:

{
  "mcpServers": {
    "yapi": {
      "command": "npx",
      "args": ["-y", "@zjlgdx/yapi-mcp-server@0.8.0"],
      "env": {
        "YAPI_URL": "<your-yapi-url>",
        "YAPI_PROJECT_TOKEN": "<your-project-token>"
      }
    }
  }
}

Usage Examples

Once configured, you can ask Claude to:

• "List all APIs in my YAPI project"
• "List interfaces from YAPI category URL .../cat_114557"
• "Get details for interface ID 12345"
• "Search for APIs related to 'user' in my project"
• "Show me all POST endpoints"

Troubleshooting

Server not starting

• Ensure Node.js 22+ is installed
• Verify the path to dist/index.js is correct
• Check that YAPI_URL is set and accessible

Authentication errors

• Verify your YAPI_PROJECT_TOKEN is correct
• Check token permissions in YAPI project settings

Network errors

• Ensure your YAPI instance is accessible from your machine
• Check firewall settings if using internal network

Development

# Install dependencies
npm install

# Build
npm run build

# Build and run the MCP 2026-07-28 stdio smoke tests
npm test

# Watch mode
npm run watch

# Run directly (requires env vars)
YAPI_URL=http://yapi.example.com YAPI_PROJECT_TOKEN=xxx npm start

The server is read-only: all exposed tools use YAPI GET endpoints and are advertised with MCP read-only annotations. Diagnostic output is written only to stderr; stdout is reserved for MCP messages.

Publishing

The npm package is @zjlgdx/yapi-mcp-server. The unscoped mcp-server-yapi package belongs to an unrelated publisher and must never be used as this repository's release target.

After the one-time bootstrap below, publishing is performed only by .github/workflows/publish.yml when a stable GitHub Release is published. The release tag must be v<package.json version>, point to a commit on main, and pass the same build, test, audit, and package-content gates used by CI. The workflow uses npm Trusted Publishing through GitHub OIDC; do not add an NPM_TOKEN secret or use manual publishing as a fallback.

Because npm requires a package to exist before Trusted Publishing can be configured, the owner of the npm zjlgdx user or organization scope must perform a one-time bootstrap with an npm account protected by 2FA:

1. Confirm that the authenticated npm account owns the @zjlgdx scope.
2. From a temporary clean copy of an exact, verified main commit, set a disposable prerelease version such as 0.0.0-bootstrap.0 without committing it, then run npm publish --access public --tag bootstrap. Do not manually publish a stable release version.
3. Immediately configure Trusted Publishing on the new package with these exact values:

• Publisher: GitHub Actions
• Organization or user: zjlgdx
• Repository: yapi-mcp-server
• Workflow filename: publish.yml
• Environment: npm
• Allowed action: npm publish

4. Set package publishing access to require 2FA and disallow traditional tokens.

The bootstrap prerelease is the only manual publish. Every stable version must use the release workflow. The GitHub npm environment must allow only tags matching v*. Enable required reviewers when a reviewer distinct from the releaser is available. Trusted Publishing requires a public GitHub-hosted runner and automatically generates npm provenance for this public package.

License

MIT