将 OpenAPI 文件连接到 AI

Apidog MCP Server 可以直接读取 Swagger 或 OpenAPI Specification (OAS) 文件，使 AI 助手能够独立于 Apidog 项目或在线文档来处理 API 规范。

前提条件

在配置 MCP 客户端之前，请确保你已具备：

Node.js（版本 18 或更高，最好是最新的 LTS 版本）

一个 兼容 MCP 的 IDE：

Cursor

VS Code + Cline 插件

其他支持 MCP 的编辑器

一个 Swagger/OpenAPI 文件（URL 或本地路径）

准备你的 OpenAPI 文件

确保你拥有以下任意一种：

远程 URL：一个可公开访问的 OpenAPI 文件（例如 https://petstore.swagger.io/v2/swagger.json）

本地文件路径：你机器上的 OpenAPI 文件（例如 ~/data/petstore/swagger.json）

支持的格式： JSON 或 YAML

配置概览

OpenAPI 文件的基本 MCP 配置：

macOS / Linux

Windows

{
  "mcpServers": {
    "API specification": {
      "command": "npx",
      "args": [
        "-y",
        "apidog-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 specification": {
      "command": "npx",
      "args": [
        "-y",
        "apidog-mcp-server@latest",
        "--oas=https://petstore.swagger.io/v2/swagger.json"
      ]
    }
  }
}

验证配置

通过询问 AI（在 Agent 模式下）来测试连接：

Please fetch API documentation via MCP and tell me how many endpoints exist in the project

如果 AI 从你的 OpenAPI 文件中返回了正确的 API 信息，则表示连接成功。

重要说明

使用多个 OpenAPI 文件

要使用多个 OpenAPI 规范文件，请在配置文件中添加多个 MCP Server，每个服务器使用不同的 --oas 参数。

示例：

{
  "mcpServers": {
    "Petstore API": {
      "command": "npx",
      "args": [
        "-y",
        "apidog-mcp-server@latest",
        "--oas=https://petstore.swagger.io/v2/swagger.json"
      ]
    },
    "Local API": {
      "command": "npx",
      "args": [
        "-y",
        "apidog-mcp-server@latest",
        "--oas=~/data/my-api/openapi.yaml"
      ]
    }
  }
}

文件路径和 URL 要求

本地文件路径：确保路径正确且文件存在

URL：确保它们可公开访问，并返回有效的 OpenAPI 规范文件

性能注意事项

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

本地化部署

对于本地化部署，请在 IDE MCP 配置中包含你的服务器 API 地址：

{
  "mcpServers": {
    "API specification": {
      "command": "npx",
      "args": [
        "-y",
        "apidog-mcp-server@latest",
        "--oas=<oas-url-or-path>",
        "--apidog-api-base-url=<your-server-url>"
      ]
    }
  }
}

将 <your-server-url> 替换为你的本地化服务器 API 地址（以 http:// 或 https:// 开头）。确保可以通过网络访问 www.npmjs.com。

其他数据源

将 Apidog 项目中的 API 规范连接到 AI

将 Apidog 发布的在线 API 文档连接到 AI

常见问题

Windows 配置问题

如果标准配置在 Windows 上失败，请使用此替代方案：

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

Node.js 版本问题

将 OpenAPI 文件连接到 AI

前提条件#

准备你的 OpenAPI 文件#

配置概览#

在 Cursor 中配置 MCP#

重要说明#

使用多个 OpenAPI 文件#

文件路径和 URL 要求#

性能注意事项#

本地化部署#

其他数据源#

常见问题#