YAPI MCP Server

中文文档 | English

一个基于FastMCP构建的YAPI接口文档查询工具，使AI助手能够访问来自YAPI平台的接口文档。

特性

项目管理

• 获取项目基本信息
• 获取项目列表
• 获取项目成员列表

接口管理

• 获取接口文档（请求参数和响应结构）
• 获取项目的接口列表
• 按类别获取接口列表
• 通过关键词搜索接口

数据导入

• 导入Swagger/OpenAPI数据
• 导入Postman数据
• 导入JSON数据

自动化测试

• 运行自动化测试
• 获取测试报告

通用功能

• 支持LDAP登录认证
• 自动管理登录状态
• 通过MCP协议与AI助手集成

安装

从源代码安装

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

cd yapi-mcp

pip install -e .

或者使用uv：

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

cd yapi-mcp

uv pip install -e .

从PyPI安装（即将推出）

配置

通过环境变量配置YAPI连接：

export YAPI_BASE_URL="https://your-yapi-server.com"

export YAPI_EMAIL="your-email@example.com"

export YAPI_PASSWORD="your-password"

配置选项

环境变量	描述
YAPI_BASE_URL	YAPI服务器地址
YAPI_EMAIL	登录邮箱
YAPI_PASSWORD	登录密码

使用

使用uv运行（推荐）

uv run yapi-mcp

使用python -m运行

python -m yapi_mcp

直接运行

yapi-mcp

作为MCP服务器使用

使用uv运行（推荐）

{

  "mcpServers": {

    "yapi": {

      "command": "uv",

      "args": [

        "--directory",

        "/path/to/yapi-mcp",

        "run",

        "yapi-mcp"

      ],

      "env": {

        "YAPI_BASE_URL": "https://your-yapi-server.com",

        "YAPI_EMAIL": "your-email@example.com",

        "YAPI_PASSWORD": "your-password"

      }

    }

  }

}

使用uvx运行（即将推出）

{

  "mcpServers": {

    "yapi": {

      "command": "uvx",

      "args": [

        "yapi-mcp"

      ],

      "env": {

        "YAPI_BASE_URL": "https://your-yapi-server.com",

        "YAPI_EMAIL": "your-email@example.com",

        "YAPI_PASSWORD": "your-password"

      }

    }

  }

}

直接使用Python运行

Claude Desktop配置

添加到Claude Desktop配置文件中：

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

{

  "mcpServers": {

    "yapi": {

      "command": "python",

      "args": ["-m", "yapi_mcp"],

      "env": {

        "YAPI_BASE_URL": "https://your-yapi-server.com",

        "YAPI_EMAIL": "your-email@example.com",

        "YAPI_PASSWORD": "your-password"

      }

    }

  }

}

Cursor / VS Code配置

{

  "mcp": {

    "servers": {

      "yapi": {

        "command": "uv",

        "args": [

          "--directory",

          "/path/to/yapi-mcp",

          "run",

          "yapi-mcp"

        ],

        "env": {

          "YAPI_BASE_URL": "https://your-yapi-server.com",

          "YAPI_EMAIL": "your-email@example.com",

          "YAPI_PASSWORD": "your-password"

        }

      }

    }

  }

}

MCP工具

项目工具

获取项目基本信息

获取YAPI项目的基本信息。

参数:

• project_id (int): 项目ID

返回: 项目基本信息字典

---

获取项目列表

获取当前用户可访问的所有项目。

返回: 项目列表

---

获取项目成员列表

获取指定项目的成员列表。

参数:

• project_id (int): 项目ID

返回: 成员列表

接口管理工具

获取接口文档

获取YAPI接口文档信息。

参数:

• url (string): YAPI接口URL，例如：https://yapi.example.com/project/123/interface/api/456

返回:

• title: 接口名称
• request: 请求参数结构
• response: 响应数据结构

---

获取接口列表

获取项目的接口列表，可选地按类别ID过滤。

参数:

• project_id (int): 项目ID
• cat_id (int, 可选): 类别ID，如果不提供则检索所有接口

返回: 接口列表

---

获取类别接口列表

获取特定类别的所有接口。

参数:

• cat_id (int): 类别ID

返回: 接口列表

---

搜索接口

在项目中搜索包含关键词的接口。

参数:

• project_id (int): 项目ID
• keyword (string): 搜索关键词

返回: 匹配的接口列表

数据导入工具

导入Swagger数据

从URL或JSON导入Swagger/OpenAPI数据到YAPI。

参数:

• url (string, 可选): Swagger数据的URL
• json (string, 可选): Swagger JSON字符串
• project_id (int, 可选): 目标项目ID
• merge (string, 可选): 合并策略，选项：normal, good, merge（默认：normal）

返回: 导入结果

---

导入Postman数据

从URL或JSON导入Postman数据到YAPI。

参数:

• url (string, 可选): Postman数据的URL
• json (string, 可选): Postman JSON字符串
• project_id (int, 可选): 目标项目ID- merge (字符串，可选)：合并策略，选项：normal、good、merge（默认值：normal）

返回值： 导入结果

---

导入 JSON 数据

将 JSON 数据导入 YAPI。

参数：

• json (字符串)：JSON 数据字符串
• project_id (整数)：目标项目 ID
• merge (字符串，可选)：合并策略，选项：normal、good、merge（默认值：normal）

返回值： 导入结果

自动化测试工具

运行自动化测试

运行自动化测试并返回测试报告。

参数：

• col_id (整数)：测试集合 ID
• project_id (整数)：项目 ID
• token (字符串)：项目令牌
• mode (字符串，可选)：报告模式，选项：html、json（默认值：html）
• email (布尔值，可选)：是否发送电子邮件通知（默认值：False）

返回值： 测试报告

使用示例

使用 AI 助手，您可以执行以下操作：

# Get interface documentation

Please get the documentation for interface https://yapi.example.com/project/123/interface/api/456



# Get project list

Please get all projects I have access to



# Get project members

Please get the member list for project 123



# Search interfaces

Please search for interfaces containing "user" keyword in project 123



# Import data

Please import this Swagger document to project 123: https://example.com/swagger.json



# Run tests

Please run automation tests for project 123, test collection ID is 456

项目结构

yapi-mcp/

├── src/

│   └── yapi_mcp/

│       ├── __init__.py      # Package entry, exports main modules

│       ├── __main__.py      # CLI entry point

│       ├── server.py        # MCP server and tool definitions

│       ├── client.py        # YAPI client class

│       └── config.py        # Configuration management

├── tests/

│   ├── __init__.py

│   └── test_config.py       # Configuration tests

├── pyproject.toml           # Project configuration

├── .gitignore              # Git ignore file

└── README.md               # This document

重要注意事项

1. 安全性：不要硬编码凭据或将它们提交到版本控制系统
2. 环境变量：在生产或共享环境中使用环境变量配置敏感信息
3. LDAP 登录：目前仅支持 LDAP 登录。如果需要其他登录方式，请修改 login() 方法

故障排除

登录失败

• 检查电子邮件和密码是否正确
• 确认 YAPI 服务器地址是否正确（不要以 / 结尾）
• 确认服务器支持 LDAP 登录

配置未生效

• 验证环境变量是否设置正确
• 检查环境变量名称：YAPI_BASE_URL、YAPI_EMAIL、YAPI_PASSWORD

许可证

MIT