@openapi-mcp/server

openapi-mcp-server 是一个强大的桥梁，连接 OpenAPI 规范与使用模型上下文协议（MCP）的AI助手。它会自动将任何 OpenAPI/Swagger API 规范转换成可以被像 Claude Desktop 这样的AI助手使用的 MCP 工具。这使得AI助手能够无缝地与您的API进行交互，通过您的服务执行实际操作，而无需定制集成。

功能

⚠️ 注意： 此服务器需要您在 OpenAPI/Swagger 规范中的每个操作都具有一个 operationId。如果任何操作缺少 operationId，服务器将无法启动或处理该规范。始终确保所有操作都被明确分配了一个唯一且描述性的 operationId。

• 🔌 OpenAPI 集成
  • 自动将 OpenAPI/Swagger 规范转换为 MCP 工具
• 📚 支持多个 OpenAPI 版本
  • 支持 OpenAPI v3.0.0 和 v3.1.0
• 🔐 认证支持：
  • HTTP 认证方案：
    • 基本认证
    • 承载令牌认证（静态令牌，例如个人访问令牌）
    • 其他由 RFC 7235 定义的 HTTP 方案
  • API 密钥：
    • 基于头部的 API 密钥

限制

⚠️ 版本支持：

• 当前不支持 OpenAPI v2.0 (Swagger)

⚠️ 认证限制：

• 不支持 OAuth 2.0 认证
• 不支持 OpenID Connect 发现
• 不支持基于查询参数的 API 密钥
• 不支持基于 Cookie 的认证
• 不支持动态 JWT 认证（登录生成的令牌）

安装

# 克隆仓库
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 对象 的 URL

• HEADERS

  • 必需：否
  • 默认值：{"Content-Type": "application/json","User-Agent": "openapi-m_ 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. 点击 "+ 添加新的全局 MCP 服务器"
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: 返回特定用户的详细信息

包含详细的操作描述

每个操作的 description 字段同样重要：

• 工具选择：AI 助手使用此描述来确定哪个工具适合给定任务
• 理解：全面的描述帮助 AI 理解操作的具体内容
• 上下文：包括关于参数、预期响应和潜在错误的信息

一个描述良好的操作示例：

paths:
  /users:
    post:
      operationId: createUser
      summary: 创建新用户账户
      description: |
        在系统中创建一个新用户。需要一个唯一的电子邮件地址和符合安全要求的密码（最小8个字符，包括大写、小写和数字）。返回创建的用户对象及其分配的用户ID。

没有详细的描述，AI 助手可能会难以识别用户请求的正确操作，或者可能错误地使用它们。您的 API 描述的质量直接影响到 AI 如何有效地利用您的工具。

开发

开发命令

# 运行测试
bun vitest run

# 运行带有监视模式的测试
bun vitest

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

# 格式化代码
bun prettier . --write

手动发布流程（使用发布分支）

本节概述了使用专用发布分支创建新发布的手动步骤。这种方法有助于将发布过程从 main 分支隔离，直到发布。

前提条件：

• 意图发布的所有更改已合并到 main 分支。
• 您已登录到 npm 账户 (npm login)。
• 可以访问 Changesets CLI（本指南使用 bunx）。

步骤：

1. 确保 main 是最新的：

   git checkout main
   git pull origin main
   

2. 创建发布分支： 根据您打算发布的版本命名（例如，v0.1.0）。

   git checkout -b release/vX.Y.Z main
   

   将 vX.Y.Z 替换为目标版本。

3. 更新版本和变更日志： 此命令消耗变更集文件（在 .changeset/ 中），更新 package.json 中的版本，并更新 CHANGELOG.md。

   bunx @changesets/cli version
   

   查看对 package.json 和 CHANGELOG.md 的更改，确保它们正确无误。

4. 提交版本更改：

   git add .
   git commit -m "chore: 更新版本和变更日志至 vX.Y.Z"
   

   将 vX.Y.Z 替换为目标版本。

5. 构建项目： 确保生成最新的更改分布文件。

   bun run build
   

6. 发布到 npm： 将新版本发布到 npm 注册表。

   npm publish
   

   确保您的 package.json 包含 "publishConfig": { "access": "public" } 用于公开的包。 （您也可以使用 bun publish，但如果您选择此选项，请确认其行为适用于公开的包）。

7. 在 Git 中标记发布： 创建一个与发布到 npm 的版本相匹配的 Git 标签。

   # 将 X.Y.Z 替换为实际版本号，例如 0.1.0
   git tag @openapi-mcp/server@X.Y.Z
   

8. 将发布分支合并回 main： 这将版本提升和变更日志更新带入您的主分支。

   git checkout main
   git merge --no-ff release/vX.Y.Z
   

   （使用 --no-ff 创建合并提交，这有助于在 Git 历史记录中跟踪发布）。

9. 推送 main 和新标签到远程仓库：

   git push origin main --tags
   

10. （可选）清理： 如果不再需要，删除本地和远程的发布分支。

    git branch -d release/vX.Y.Z
    git push origin --delete release/vX.Y.Z
    

有关使用 Changesets 的更详细信息，请参阅 官方 Changesets 文档。