Simple YAPI MCP Server

中文 | English

一个简单的利用YAPI openapi能力的mcp server实现，让ai agents能够直接访问和操作YAPI中的API文档信息。

基于modelcontextprotocol sdk实现。

已实现功能

✅ 获取项目信息和接口数据
✅ 管理接口分类
✅ 添加新接口
✅ 更新已有接口

安装与使用

0.获取YAPI项目token

YApi的token是项目粒度的，每个项目不同，获取位置在项目的「设置」→ 「token配置」中。

此菜单需要有项目「开发者」或「组长」的权限才可以看到，如果你没看到，请首先确认权限。

token具有新增/编辑接口的权限，请务必确认权限范围。

1.在工具中添加配置

baseUrl和token是必须参数，可以通过env变量控制或者在对话时提供给AI，0.0.3以上的版本已经支持MCP Elicitation，支持的客户端会询问用户。 调用成功后的baseUrl和token会被缓存起来，默认缓存时间为15分钟，可以通过env环境变量配置YAPI_CREDENTIAL_TTL_MINUTES控制。

使用npx

增加mcpServers的配置，下列为cursor中的示例：

{
  "mcpServers": {
    "simple-yapi-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "simple-yapi-mcp"
      ],
      "env": {
        "YAPI_BASE_URL": "<yapi host>",
        "YAPI_PROJECT_TOKEN": "<yapi token>"
      }
    }
  }
}

其中env配置中的YAPI_BASE_URL和YAPI_PROJECT_TOKEN并非必填，你可以在调用agent时再告诉agent。根据配置的场景，比如全局使用时就可以不添加配置或者只添加YAPI_BASE_URL的配置。

如果是按项目维度做的mcp配置，那建议都用env来配置参数，因为单项目的baseUrl和token一般是固定的。

全局安装

通过全局安装simple-yapi-mcp来增加mcp servers。

npm install -g simple-yapi-mcp

配置文件：

{
  "mcpServers": {
    "simple-yapi-mcp": {
      "command": "simple-yapi-mcp",
      "args": [],
      "env": {
        "YAPI_BASE_URL": "<yapi host>",
        "YAPI_PROJECT_TOKEN": "<yapi token>"
      }
    }
  }
}

本地clone项目

如果是本地clone的项目，那需要先安装相应的依赖并执行转译

cd "<clone dir>"
npm install
npm run build

再增加配置

{
  "mcpServers": {
    "simple-yapi-mcp": {
      "command": "node",
      "args": [
        "<clone dir>/dist/index.js"
      ],
      "env": {
        "YAPI_BASE_URL": "<yapi host>",
        "YAPI_PROJECT_TOKEN": "<yapi token>"
      }
    }
  }
}

2. AI agent使用建议

因为agent解析意图再调用工具，在声明意图时，建议直接强调YAPI。所有暴露的tool都添加了yapi_的前缀，也是用于更好的区分，避免与其他工具混淆。

用法示例

基本查询

"查询YAPI中标签管理接口，为当前ts文件增加types信息"
"根据YAPI项目中的用户信息接口为它编写测试用例"

添加和修改

"在YAPI项目添加一个"用户系统"分类"
"为当前的接口代码增加YAPI接口信息并放在"用户系统"分类下"
"创建一个POST YAPI接口用于上传用户头像，需要支持文件上传"
"更新ID为12345的YAPI接口，添加一个新的查询参数"

具体tool信息

YAPI MCP提供以下工具，所有工具名称均以yapi_开头，以便于AI助手识别关键字：

• yapi_get_project: 获取YAPI项目信息，包括名称、描述、项目ID和基础路径
• yapi_get_interface_list: 获取项目中所有API接口的分页列表
• yapi_get_interface: 根据ID获取特定API接口的详细信息
• yapi_get_category_list: 获取项目中所有API分类/文件夹的列表
• yapi_get_category_interfaces: 获取特定分类中API接口的分页列表
• yapi_add_category: 在YAPI项目中创建新的API分类/文件夹（需要提供项目ID）
• yapi_get_interface_menu_list: 获取接口和分类的层次菜单结构
• yapi_add_interface: 在指定分类下添加一个新的接口，支持各种HTTP方法和请求参数
• yapi_update_interface: 更新已有接口的信息，可以修改接口的路径、方法、请求参数等

开发与调试

项目本身简单，就一个typescript项目，没有什么需要特殊说明的。

自行mcp server调试比较麻烦，推荐使用@modelcontextprotocol/inspector：

npx @modelcontextprotocol/inspector node dist/index.js

# 如果需要调试环境变量，使用 -e 参数，多个环境变量多次添加
npx @modelcontextprotocol/inspector -e YAPI_BASE_URL=<yapi host> -e YAPI_PROJECT_TOKEN=<token> node dist/index.js

执行后按说明打开调试页面即可连接本地服务器和调试tools。