YAPI MCP Server by xrf-9527 - MCP Server

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.

Features

List Interfaces: Get all interface categories and basic interface info within a project
Get Interface Details: Retrieve detailed information for a specific interface by its ID
Search Interfaces: Search for interfaces by keyword in titles or paths

Tools

`yapi_list_interfaces`

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

Input:

project_token (optional): The token for the YAPI project. Not required if YAPI_PROJECT_TOKEN env is set.

Returns: JSON array of categories with simplified interface objects (id, title, path, method, status).

`yapi_get_interface_details`

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

Input:

project_token (optional): The token for the YAPI project. Not required if YAPI_PROJECT_TOKEN env is set.
interface_id (number, required): The ID of the specific YAPI interface.

Returns: JSON object with full interface specification (request/response parameters, headers, body schemas, etc.).

`yapi_search_interfaces`

Searches for interfaces by keyword in their titles or paths.

Input:

project_token (optional): The token for the YAPI project. Not required if YAPI_PROJECT_TOKEN env is set.
keyword (string, required): The keyword to search for.

Returns: JSON array of matching interfaces with their category information.

Prerequisites

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

Environment Variables

Variable	Required	Description
`YAPI_URL`	Yes	Base URL of your YAPI instance (e.g., `http://yapi.example.com`)
`YAPI_PROJECT_TOKEN`	No	Default project token. If set, `project_token` parameter becomes optional in tool calls

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)

If published to npm, use npx for automatic version management:

{
  "mcpServers": {
    "yapi": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-yapi"],
      "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"
"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 18+ 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

# Watch mode
npm run watch

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