Yapi MCP Server

A Model Context Protocol (MCP) Server for Yapi API documentation platform. Provides seamless integration between AI assistants and Yapi, allowing you to query API interface details through natural language.

Features

• getInterfaceDetail - Get detailed information about a specific Yapi API interface

Quick Start

Installation

# Clone the repository (or navigate to the project directory)
cd yapi-mcp-server

# Install dependencies
npm install

# Build the project
npm run build

Configuration

The server uses environment variables for Yapi connection settings:

# Yapi server URL
YAPI_URL=http://yapi.example.com

# Project tokens in JSON format: {"projectId": "token", "123": "your-token-1"}
YAPI_PROJECT_TOKENS={"123":"your-token-1","456":"your-token-2"}

You can create a .env file or pass these directly as environment variables.

Usage

With OpenCode

Add to your MCP configuration:

{
  "mcp": {
    "yapi": {
      "type": "local",
      "command": [
        "node",
        "/path/to/yapi-mcp-server/dist/index.js"
      ],
      "environment": {
        "YAPI_URL": "your_yapi_url",
        "YAPI_PROJECT_TOKENS": "{\"123\":\"your-project-token\"}"
      }
    }
  }
}

With Cursor IDE

Add to your MCP configuration file (mcp.json):

{
  "mcpServers": {
    "yapi": {
      "command": "node",
      "args": ["path/to/yapi-mcp-server/dist/index.js"],
      "env": {
        "YAPI_URL": "your_yapi_url",
        "YAPI_PROJECT_TOKENS": "{\"123\":\"your-project-token\"}"
      }
    }
  }
}

Available Tools

getInterfaceDetail

Get detailed information about a specific Yapi API interface.

Parameters:

• interfaceId (required): Yapi interface ID
• projectId (required): Yapi project ID (used to get token)

Example:

{
  "interfaceId": 789,
  "projectId": 123456
}

Returns:

• Basic info (ID, title, path, method)
• Request info (request body type, parameters, headers, query)
• Response info (response body type, response body, JSON schema flag)
• Other info (status, markdown documentation)

Development

# Install dependencies
npm install

# Development mode (watch for changes)
npm run dev

# Build for production
npm run build

# Start the server
npm start

Project Structure

yapi-mcp-server/
├── src/
│   ├── index.ts          # Main MCP server implementation
│   └── env.ts            # Environment variable configuration
├── dist/                 # Compiled JavaScript (auto-generated)
├── package.json          # Project dependencies and scripts
├── tsconfig.json         # TypeScript configuration
├── .env.example          # Environment variable template
└── README.md            # This file

Error Handling

• BusinessException: Business logic errors (e.g., missing project token, Yapi API errors)
• HTTP errors: Network or Yapi server errors
• Validation errors: Invalid environment variables or request parameters

License

MIT License