项目简介

openapi-mcp-server 是一个桥梁，它使用 Model Context Protocol (MCP) 将 OpenAPI (Swagger) 规范转换为 AI 助手可以理解和调用的工具。无需任何定制集成，即可让 AI 助手（如 Claude Desktop、Cursor）直接与您的 API 交互，执行各种真实世界的操作。

主要功能点

OpenAPI 自动集成: 自动将 OpenAPI/Swagger 规范转换为 MCP 工具，无需手动定义。
多版本 OpenAPI 支持: 支持 OpenAPI v3.0.0 和 v3.1.0 规范。
参数自动校验: 使用 Zod 自动校验 API 参数，确保请求的有效性。
多种身份验证支持:
- HTTP 基础认证 (Basic Authentication)
- Bearer Token 认证 (JWT)
- API Key 认证 (Header-based)
- 支持 RFC 7235 定义的其他 HTTP 认证方案

安装步骤

克隆仓库

git clone https://github.com/sotayamashita/openapi-mcp-server.git
cd openapi-mcp-server

安装依赖

确保您已安装 Bun 包管理器。然后运行：
```
bun install
```

服务器配置

要将此 MCP 服务器与 MCP 客户端（例如 Claude Desktop 或 Cursor）集成，您需要配置客户端以启动并连接到此服务器。以下是 Claude Desktop 和 Cursor 的配置示例。

Claude Desktop 集成配置 (JSON 格式)

{
  "mcpServer": {
    "openapi-mcp-server": {
      "command": "bun",
      "args": [
        "/path/to/openapi-mcp-server/src/index.ts",  // openapi-mcp-server 入口文件路径
        "/path/to/your/openapi.yml"                 // 您的 OpenAPI 规范文件路径 (本地文件或 URL)
      ],
      "env": {
        "BASE_URL": "https://api.example.com/v1/",    // 您的 API 基础 URL，必须设置
        "HEADERS": "{\"Authorization\": \"Bearer YOUR_API_TOKEN\"}" // 可选，自定义 HTTP 请求头，例如用于 API 密钥或 Bearer Token 认证
      }
    }
  }
}

Cursor 集成配置 (JSON 格式)

{
  "mcpServer": {
    "openapi-mcp-server": {
      "command": "bun",
      "args": [
        "/path/to/openapi-mcp-server/src/index.ts",  // openapi-mcp-server 入口文件路径
        "/path/to/your/openapi.yml"                 // 您的 OpenAPI 规范文件路径 (本地文件或 URL)
      ],
      "env": {
        "BASE_URL": "https://api.example.com/v1/",    // 您的 API 基础 URL，必须设置
        "HEADERS": "{\"X-API-KEY\": \"YOUR_API_KEY\"}"   // 可选，自定义 HTTP 请求头，例如用于 API 密钥认证
      }
    }
  }
}

配置参数说明:

'command': 启动 MCP 服务器的命令，这里使用 'bun'。
'args': 传递给 'bun' 命令的参数，包括：
- openapi-mcp-server 的入口文件路径 ('/path/to/openapi-mcp-server/src/index.ts')。
- 您的 OpenAPI 规范文件路径，可以是本地文件路径 ('/path/to/your/openapi.yml') 或 URL ('https://example.com/api-spec.json')。
'env': 环境变量配置，用于配置服务器运行时的环境参数：
- 'BASE_URL': 必填，您的 API 服务的根 URL。请替换为实际的 API Endpoint。
- 'HEADERS': 可选，JSON 格式的字符串，用于设置 HTTP 请求头。例如，当您的 API 需要身份验证时，您可以通过 'HEADERS' 传递 'Authorization' 或其他自定义 Header。

注意:

请将 '/path/to/openapi-mcp-server' 和 '/path/to/your/openapi.yml' 替换为实际的路径。
'BASE_URL' 环境变量是 必需的，请务必根据您的 API 服务进行配置。
'HEADERS' 环境变量是 可选的，如果您的 API 需要身份验证，请根据实际情况配置。

基本使用方法

启动服务器

在仓库根目录下，使用以下命令启动服务器，并指定 OpenAPI 规范文件路径或 URL：

# 使用本地文件
bun run src/index.ts ./path/to/openapi.yml

# 使用 URL
bun run src/index.ts --api https://example.com/api-spec.json

配置 MCP 客户端

根据您使用的 MCP 客户端（如 Claude Desktop、Cursor），按照上述 服务器配置 部分的说明进行配置，确保客户端能够连接到您启动的 openapi-mcp-server。
在 AI 助手中使用工具

配置完成后，您的 AI 助手应该能够识别并使用由 openapi-mcp-server 提供的工具。工具名称通常会基于 OpenAPI 规范中的 'operationId' 字段生成。您可以通过自然语言指示 AI 助手调用这些工具，与您的 API 进行交互。

最佳实践

使用描述性的 'operationId': 在 OpenAPI 规范中，'operationId' 直接作为 MCP 工具的名称。使用清晰、描述性的 'operationId' 有助于 AI 助手更好地理解和使用您的 API 工具。

关键词