通过 MCP 使用 OpenAPI/Swagger 文档

除了 Apifox 项目、在线文档之外，Apifox MCP Server 可以直接读取 Swagger/OpenAPI 文件，将内容提供给 AI 使用。

配置 MCP 客户端

前置条件

已安装 Node.js 环境（版本号 >= 18，推荐最新的 LTS 版本）

任意一个支持 MCP 的 IDE：

Cursor

VSCode + Cline 插件

其它

基本步骤

准备 OpenAPI 文件

确保你有 Swagger/OpenAPI 文件的 URL 或本地路径

支持的格式：JSON 或 YAML 格式的 OpenAPI 文件

在 IDE 中配置 MCP

将下面 JSON 配置添加到 IDE 对应的 MCP 配置文件里：

macOS / Linux

Windows

{
  "mcpServers": {
    "API 文档": {
      "command": "npx",
      "args": [
        "-y",
        "apifox-mcp-server@latest",
        "--oas=<oas-url-or-path>"
      ]
    }
  }
}

其中 <oas-url-or-path> 可以是:

远程 URL，如：https://petstore.swagger.io/v2/swagger.json

本地文件路径，如：~/data/petstore/swagger.json

在 Cursor 中配置 MCP

编辑 MCP 配置文件

打开 Cursor 编辑器，点击右上角「设置」图标，选择左侧「MCP」选项，点击「+ Add new global MCP server」按钮。

添加配置内容

在打开的 mcp.json 文件中添加以下配置，注意替换 https://petstore.swagger.io/v2/swagger.json 为你的 OpenAPI 文件路径或 URL：

macOS / Linux

Windows

{
  "mcpServers": {
    "API 文档": {
      "command": "npx",
      "args": [
        "-y",
        "apifox-mcp-server@latest",
        "--oas=https://petstore.swagger.io/v2/swagger.json"
      ]
    }
  }
}

验证配置

配置完成后，你可以通过向 AI 询问以验证连接是否正常工作（Agent 模式），例如：

请通过 MCP 获取 API 文档，并告诉我项目中有几个接口

如果 AI 能够返回你 OpenAPI 规范中的 API 信息，说明连接成功。

在 Cline 中配置 MCP

安装 Cline 插件

在 VSCode 扩展市场搜索并安装 “Cline” 插件

配置 MCP 服务器

打开 Cline 面板，点击「MCP Servers > Configure MCP Servers」。

在打开的 .json 文件中添加以下配置，注意替换 <oas-url-or-path> 为你的 OpenAPI 文件路径或 URL：

macOS / Linux

Windows

{
  "mcpServers": {
    "API 文档": {
      "command": "npx",
      "args": [
        "-y",
        "apifox-mcp-server@latest",
        "--oas=https://petstore.swagger.io/v2/swagger.json"
      ]
    }
  }
}

验证配置

配置完成后，你可以通过向 AI 询问以验证连接是否正常工作，例如：

请通过 MCP 获取 API 文档，并告诉我项目中有几个接口

如果 AI 能够返回你 OpenAPI 规范中的 API 信息，说明连接成功。

注意事项

如果需要使用多个 OpenAPI 规范文件，可以在配置文件中添加多个 MCP Server，每个使用不同的 --oas 参数值。

对于本地文件路径，确保路径正确且文件存在。对于 URL，确保 URL 可以公开访问且返回有效的 OpenAPI 规范文件。

如果你的 OpenAPI 规范文件较大或包含复杂的数据结构，MCP 服务器可能需要更多时间来处理。

使用私有化部署版本的用户，请在 IDE 的 MCP 的配置文件添加参数："--apifox-api-base-url=<私有化部署服务器的 API 地址，以 http:// 或 https:// 开头>"。另外，请确保网络可以正常访问 www.npm.com。

{
  "mcpServers": {
    "API 文档": {
      "command": "npx",
      "args": [
        "-y",
        "apifox-mcp-server@latest",
        "--oas=<oas-url-or-path>",
        // 私有化部署必须添加以下参数
        "--apifox-api-base-url=<私有化部署服务器的API地址>"
      ]
    }
  }
}

其他使用方法

通过 MCP 使用 Apifox 项目内的 API 文档

通过 MCP 使用公开发布的 API 文档

常见问题

Windows 系统配置问题

如果在 Windows 操作系统上，前述配置无法正常工作，请使用以下配置：

{
  "mcpServers": {
    "API 文档": {
      "command": "cmd",
      "args": [
        "/c",
        "npx",
        "-y",
        "apifox-mcp-server@latest",
        "--oas=<oas-url-or-path>"
      ]
    }
  }
}

Node.js 版本问题

通过 MCP 使用 OpenAPI/Swagger 文档

配置 MCP 客户端#

前置条件#

基本步骤#

在 Cursor 中配置 MCP#

在 Cline 中配置 MCP#

注意事项#

其他使用方法#

常见问题#

配置 MCP 客户端

前置条件

基本步骤

在 Cursor 中配置 MCP

在 Cline 中配置 MCP

注意事项

其他使用方法

常见问题