YAPI MCP PRO Server

You set up and operate a MCP server that connects YApi to AI editors, enabling seamless API lifecycle management across projects. This server supports multiple connection methods, automatic token/cookie authentication, and flexible configuration so you can manage interfaces, projects, categories, tests, and exports directly from your AI workflows or local tooling.

How to use

You will use MCP clients to connect to the MCP server and perform CRUD operations on interfaces, manage projects and categories, run tests, and import/export data. Two common patterns exist: running the MCP as a local process via an npm package (stdio mode) and connecting to a locally hosted HTTP/SSE MCP server. In stdio mode, you start the MCP client with a command like npx -y yapi-mcp-pro and point it at your YApi instance. In HTTP/SSE mode, you run a local MCP server and connect your editor to http://localhost:3388/sse to receive real-time updates.

How to install

Prerequisites: install Node.js (version 16.0.0 or higher) and a modern npm. Ensure you can access your YApi instance. If you run into connectivity issues, you may need to clear the npm cache and verify token/cookie configuration.

# 1) Install Node.js (example commands for common environments)
# macOS / Linux (using official installers via browser)
# Windows (official installer via browser)

# 2) Verify installations
node --version
npm --version
npx --version

# 3) Install MCP package globally (stdio mode)
npm install -g yapi-mcp-pro

# 4) Optional: test help output
npx -y yapi-mcp-pro --help

Configuration and usage notes

Configure MCP in one of two main ways: (A) as a stdio-based local client that runs via npx yapi-mcp-pro, or (B) as an HTTP/SSE local server you run and connect to from editors. You will provide the YApi base URL and authentication in environment variables. The server can read YAPI_BASE_URL and YAPI_TOKEN from the environment to perform authenticated operations.

# Example: stdio mode configuration for a project using Cursor (project-level)
{
  "mcpServers": {
    "yapi-mcp-pro": {
      "command": "npx",
      "args": ["-y", "yapi-mcp-pro"],
      "env": {
        "YAPI_BASE_URL": "http://your-yapi-server.com",
        "YAPI_TOKEN": "_yapi_token=your_token; _yapi_uid=your_uid",
        "NODE_ENV": "cli",
        "YAPI_LOG_LEVEL": "info",
        "YAPI_CACHE_TTL": "10"
      }
    }
  }
}

Or, if you prefer an HTTP/SSE server you run locally, start the MCP service and connect editors to the SSE endpoint.

# Start local MCP server (HTTP/SSE mode) and expose the SSE endpoint
# This assumes a script or command in your setup to run the server
./start-mcp.sh start

# Then connect your editor to the SSE URL
http://localhost:3388/sse

Security and best practices

Keep sensitive information secure. Do not commit .env files or tokens to version control. Use Cookie-based authentication for automatic project discovery or Token-based authentication for long-lived credentials. Regularly rotate tokens, and restrict access to the MCP server. If you stop the MCP service, use the stop command to ensure clean shutdown and cache clearing when needed.

# Safe stop example
./start-mcp.sh stop

Troubleshooting tips

If you encounter communication failures with YApi, verify the YAPI_BASE_URL is correct and that the YApi server is reachable from the MCP server. If authentication fails, re-fetch cookies or tokens and ensure they are complete and not truncated. For startup or port conflicts, adjust the PORT value in your .env or restart the MCP service.

# Check MCP process and logs
./start-mcp.sh status
./start-mcp.sh logs -f

Quick start templates

Use these templates to bootstrap a quick setup for a typical YApi MCP workflow.

# 1) Minimal stdio mode configuration snippet for Cursor
{
  "mcpServers": {
    "yapi-mcp-pro": {
      "command": "npx",
      "args": ["-y", "yapi-mcp-pro"],
      "env": {
        "YAPI_BASE_URL": "http://your-yapi-server.com",
        "YAPI_TOKEN": "_yapi_token=your_token; _yapi_uid=your_uid",
        "NODE_ENV": "cli"
      }
    }
  }
}

# 2) HTTP/SSE local server connection
{
  "mcpServers": {
    "yapi_mcp_http": {
      "type": "http",
      "name": "local_sse",
      "url": "http://localhost:3388/sse",
      "args": []
    }
  }
}

Notes

This MCP server supports multiple editors and can manage all aspects of your YApi projects, including interfaces, projects, categories, test collections, and data export/import. Choose the connection method that fits your workflow best and configure the environment variables accordingly.

Available tools

yapi_get_api_desc

Fetches full API detail for a specified interface including parameters, responses, and descriptions.

yapi_save_api

Creates a new API or updates an existing one with title, path, method, and payload definitions.

yapi_search_apis

Searches APIs across projects by name, path, or project with fuzzy matching and deduplication.

yapi_delete_interface

Deletes a specified API from a project.

yapi_copy_interface

Copies an API to a target category within a project.

yapi_list_projects

Lists all accessible projects with basic metadata.

yapi_create_project

Creates a new YApi project with basic metadata.

yapi_update_project

Updates project information such as name, path, or description.

yapi_get_categories

Retrieves categories in a project including their contained APIs.

yapi_create_category

Creates a new API category within a project.

yapi_update_category

Updates category information.

yapi_delete_category

Deletes a category from a project.

yapi_get_user_info

Fetches details about the currently authenticated user.

yapi_get_user_groups

Retrieves the groups the current user belongs to.

yapi_get_test_collections

Gets test collections for a project.

yapi_create_test_collection

Creates a new test collection within a project.

yapi_import_swagger

Imports Swagger data into a project.

yapi_export_project

Exports project data in supported formats.

yapi_run_interface

Executes a test request against an API interface.