openapi-mcp-server

openapi-mcp-server 是一个强大的桥梁，它使用模型上下文协议 (MCP) 连接 OpenAPI 规范和 AI 助手。 它可以自动将任何 OpenAPI/Swagger API 规范转换为 MCP 工具，供 Claude Desktop 等 AI 助手使用。 这使得 AI 助手能够无缝地与您的 API 交互，从而使它们能够通过您的服务执行真实世界的操作，而无需自定义集成。

特性

• 🔌 OpenAPI 集成
  • 自动将 OpenAPI/Swagger 规范转换为 MCP 工具
• 🧩 参数验证
  • 使用 Zod 自动验证 API 参数
• 📚 多个 OpenAPI 版本
  • 支持 OpenAPI v3.0.0 和 v3.1.0
• 🔐 身份验证支持:
  • HTTP 身份验证方案：
    • 基本身份验证
    • Bearer token 身份验证 (JWT)
    • RFC 7235 定义的其他 HTTP 方案
  • API 密钥：
    • 基于 Header 的 API 密钥

限制

⚠️ 版本支持:

• [ ] 目前不支持 OpenAPI v2.0 (Swagger)

⚠️ 身份验证限制:

• [ ] 不支持 OAuth 2.0 身份验证
• [ ] 不支持 OpenID Connect Discovery
• [ ] 不支持基于查询参数的 API 密钥
• [ ] 不支持基于 Cookie 的身份验证

安装

# 克隆仓库
git clone https://github.com/sotayamashita/openapi-mcp-server.git
cd openapi-mcp-server

# 安装依赖
bun install

用法

您可以通过提供 OpenAPI 规范 URL 或文件路径来运行服务器：

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

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

配置

环境变量

• BASE_URL

  • 必需：是
  • 描述：API 端点。 Server Object 的 URL

• HEADERS

  • 必需：否
  • 默认值：{"Content-Type": "application/json","User-Agent": "openapi-mcp-server"}
  • 描述：将覆盖默认标头的自定义标头

Claude Desktop 集成

要将此 MCP 服务器与 Claude Desktop 一起使用：

1. 打开您的 Claude Desktop 配置文件：

   # macOS/Linux
   code ~/Library/Application\ Support/Claude/claude_desktop_config.json
   

2. 添加以下配置：

   {
     "mcpServer": {
       "openapi-mcp-server": {
         "command": "bun",
         "args": [
           "/path/to/openapi-mcp-server/src/index.ts",
           "/path/to/openapi-mcp-server/demo/openapi.yml"
         ],
         "env": {
           "BASE_URL": "https://api.example.com/v1/",
           "HEADERS": "{\"Authorization\": \"Bearer ****\"}"
         }
       }
     }
   }
   

有关更详细的说明，请参阅 MCP 快速入门指南。

Cursor 集成

要将此 MCP 服务器与 Cursor 作为全局服务器一起使用：

1. 打开 Cursor
2. 打开 Cursor 设置 > MCP
3. 单击 "+ Add new global MCP Server"
4. 添加以下配置：

   {
     "mcpServer": {
       "openapi-mcp-server": {
         "command": "bun",
         "args": [
           "/path/to/openapi-mcp-server/src/index.ts",
           "/path/to/openapi-mcp-server/demo/openapi.yml"
         ],
         "env": {
           "BASE_URL": "https://api.example.com/v1/",
           "HEADERS": "{\"Authorization\": \"Bearer ****\"}"
         }
       }
     }
   }
   

有关更详细的说明，请参阅 Cursor 的模型上下文协议。

最佳实践

OpenAPI/Swagger 规范

使用描述性的 operationId 字段

OpenAPI/Swagger 规范中的 operationId 字段在工具如何呈现给 AI 助手中起着至关重要的作用。 将您的 API 转换为 MCP 工具时：

• 工具命名: operationId 直接用作 MCP 工具名称
• 清晰度: 描述性的 operationId 值使 AI 助手更容易理解和使用您的 API
• 一致性: 使用一致的命名模式（例如，getUser、createUser、updateUserPassword）

定义良好的操作示例：

paths:
  /users/{userId}:
    get:
      operationId: getUserById
      summary: 检索用户信息
      description: 返回有关特定用户的详细信息

如果没有 operationId，服务器会尝试使用 HTTP 方法和路径生成名称，但这不太具有描述性，并且可能导致 AI 助手的工具名称不太直观。

开发

开发命令

# 运行简单的 api 服务器以使用简单的 demo/openapi.yml 进行测试
bun start:server

# 运行 @modelcontextprotocol/inspector
bun start:inspector

# 并发运行简单的 api 服务器和 @modelcontextprotocol/inspector
bun start

# 运行测试
bun test

# 以观察模式运行测试
bun test --watch

# 运行带有覆盖率的测试
bun test --coverage

# 格式化代码
bun run format

代码库结构

有关代码库结构和模块职责的详细信息，请参阅 代码库结构。