yapi-mcp

一个基于 MCP 的 YApi 只读服务，供大模型或 MCP 客户端直接读取 YApi 中的项目、分类和接口文档，而不需要手动打开 YApi 页面。

功能

• 检查环境变量配置和登录状态
• 列出当前账号可见的 YApi 项目
• 列出指定项目下的分类
• 按关键词、项目、分类、请求方法、路径搜索接口
• 获取指定接口的最新详情
• 按需导出整个项目的 API 定义

环境要求

• Node.js 20+
• 可访问的 YApi 地址
• 有权限登录 YApi 的账号

安装

npm install

配置方式

本项目不再读取 config.json，而是从进程环境变量读取 YApi 凭据。

需要提供以下 3 个环境变量：

YAPI_BASE_URL=https://yapi.example.com
[email protected]
YAPI_PASSWORD=your-password

字段说明

• YAPI_BASE_URL: YApi 站点地址，必须是 http 或 https 开头的完整 URL
• YAPI_USERNAME: 用于登录 YApi 的用户名，当前实现按邮箱字段提交
• YAPI_PASSWORD: 对应账号密码

本地运行示例

macOS / Linux:

YAPI_BASE_URL=https://yapi.example.com \
[email protected] \
YAPI_PASSWORD=your-password \
npm start

Windows PowerShell:

$env:YAPI_BASE_URL="https://yapi.example.com"
$env:YAPI_USERNAME="[email protected]"
$env:YAPI_PASSWORD="your-password"
npm start

OpenCode MCP 配置

OpenCode 支持为本地 MCP 服务配置 environment，也支持在配置文件中使用 {env:VAR_NAME} 引用外部环境变量。

下面是一个 opencode.json 示例：

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "yapi": {
      "type": "local",
      "command": ["npx", "-y", "yapi-mcp"],
      "environment": {
        "YAPI_BASE_URL": "{env:YAPI_BASE_URL}",
        "YAPI_USERNAME": "{env:YAPI_USERNAME}",
        "YAPI_PASSWORD": "{env:YAPI_PASSWORD}"
      }
    }
  }
}

如果你不想依赖外层 shell 环境，也可以直接把值写进 environment：

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "yapi": {
      "type": "local",
      "command": ["npx", "-y", "yapi-mcp"],
      "environment": {
        "YAPI_BASE_URL": "https://yapi.example.com",
        "YAPI_USERNAME": "[email protected]",
        "YAPI_PASSWORD": "your-password"
      }
    }
  }
}

trae配置方式：

{
  "mcpServers": {
    "yapi-mcp": {
      "command": "node E:/yapi-mcp/dist/index.js",
      "env": {
        "YAPI_BASE_URL": "https://yapi.example.com",
        "YAPI_USERNAME": "[email protected]",
        "YAPI_PASSWORD": "your-password"
      }
    }
  }
}

构建

npm run build

本地运行

npm start

开发模式：

npm run dev

校验配置是否可用

构建完成后可执行：

npm run validate

该命令会输出 JSON，包含：

• 环境变量是否已提供
• 配置格式是否有效
• 是否能成功登录 YApi
• 当前会话是否可用

MCP 接入方式

这个项目通过标准输入输出运行 MCP Server，启动命令为：

node dist/index.js

如果你的 MCP 客户端支持命令行方式配置，可以将它注册为一个 stdio 服务。

可用工具

• yapi_status: 检查配置、登录和会话状态
• list_projects: 列出当前账号可见项目
• list_categories: 列出指定项目分类
• search_apis: 搜索接口
• get_api_detail: 获取接口详情
• export_project: 导出项目定义

开发脚本

• npm run dev: 直接运行 TypeScript 入口
• npm run build: 编译到 dist
• npm start: 运行编译后的 MCP Server
• npm run validate: 校验环境变量与 YApi 连接状态