openapi-mcp

OpenAPI MCP

将任意 OpenAPI 3 规范转换为可运行的 MCP 服务。单个文件，约 130 行代码，无依赖。

node openapi-mcp.mjs https://your-api.com/openapi.json

每个 API 端点都会变成一个工具，AI 客户端（Claude、Cursor 等）可以调用这些工具。无需生成代码，也无需为每个端点单独创建文件。规范会在启动时读取，工具则在内存中构建。

快速开始

需要 Node 18 或更高版本。

git clone <this-repo>
cd openapi-mcp
node openapi-mcp.mjs sample/animechan.openapi.json

它会打印 openapi-mcp: 4 tools from "Animechan" -> ...，然后静默等待 MCP 客户端。这是正常的：它通过 stdin/stdout 使用 JSON-RPC 通信，并非供人类阅读。

与 AI 客户端配合使用

Claude Desktop（本地模式）

将以下内容添加到 ~/Library/Application Support/Claude/claude_desktop_config.json，然后重启应用：

{
  "mcpServers": {
    "animechan": {
      "command": "node",
      "args": ["/full/path/openapi-mcp.mjs", "/full/path/animechan.openapi.json"]
    }
  }
}

如果客户端找不到 node，请使用 which node 获取完整路径。

Claude Code（远程模式）

启动服务，然后注册它：

MCP_AUTH_TOKEN=secret node openapi-mcp.mjs sample/animechan.openapi.json --http 8787

claude mcp add --transport http animechan http://localhost:8787/mcp \
  --header "Authorization: Bearer secret"

然后用自然语言提问：“给我一条来自 Naruto 的随机语录”。

两种模式

模式	命令	适用场景
本地（stdio）	node openapi-mcp.mjs <spec>	客户端在你的计算机上启动服务
远程（HTTP）	node openapi-mcp.mjs <spec> --http <port>	客户端连接到 URL，或你想要可自托管的服务

在 HTTP 模式下，客户端通过 POST http://host:<port>/mcp 发送 JSON-RPC 消息。请将 --http <port> 放在最后。

手动测试：

curl -X POST localhost:8787/mcp -H 'Authorization: Bearer secret' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

选项

node openapi-mcp.mjs <spec-url-or-file> [base-url] [--http <port>]

参数 / 环境变量	作用
<spec-url-or-file>	OpenAPI 3 规范，可以是 URL 或本地文件（JSON；YAML 需要 npm i yaml）
[base-url]	覆盖 API 地址。默认使用规范中的 servers[0].url
API_TOKEN	API 密钥。规范中的 securitySchemes 决定密钥的传递位置（参见身份验证）
OAUTH_CLIENT_ID、OAUTH_CLIENT_SECRET	OAuth2 客户端凭据模式：自动获取并刷新令牌
OAUTH_REFRESH_TOKEN	OAuth2 刷新令牌授权模式（与客户端 ID 和密钥配合使用）
OAUTH_TOKEN_URL、OAUTH_SCOPE	可选：覆盖规范中的 tokenUrl，或请求指定范围
API_HEADERS	每次调用都会发送的额外标头，用于处理规范未涵盖的情况。示例：'{"X-App-Id":"abc"}'
TOOL_FILTER	正则表达式。仅公开名称匹配的工具。只读示例：'^(get|list)'
MCP_AUTH_TOKEN	仅限 HTTP 模式。每个请求都必须携带 Authorization: Bearer <token>

大型 API 可能有数百个端点。工具过多会让模型更难选对，因此请使用 TOOL_FILTER 保留实用工具。

身份验证

服务器会从规范中读取 securitySchemes，并将你的密钥放到正确的位置。你只需通过环境变量提供密钥：

规范说明	设置	发送为
http / bearer	API_TOKEN=tok	Authorization: Bearer tok
http / basic	API_TOKEN=user:pass	Authorization: Basic <base64>
标头中的 apiKey	API_TOKEN=key	规范中指定的标头（例如 X-Key: key）
查询参数中的 apiKey	API_TOKEN=key	规范中指定的查询参数
Cookie 中的 apiKey	API_TOKEN=key	Cookie: name=key
oauth2 / openIdConnect，你已有访问令牌	API_TOKEN=token	Authorization: Bearer token
oauth2，机器对机器	OAUTH_CLIENT_ID + OAUTH_CLIENT_SECRET	从 tokenUrl 获取令牌并缓存，在令牌过期前续期
oauth2，你已在其他地方登录过一次	上述两个变量 + OAUTH_REFRESH_TOKEN	使用刷新令牌续期访问令牌

Claude Desktop 示例：

{
  "mcpServers": {
    "my-api": {
      "command": "node",
      "args": ["/full/path/openapi-mcp.mjs", "https://my-api.com/openapi.json"],
      "env": { "API_TOKEN": "your-secret" }
    }
  }
}

注意：

• 如果规范声明了安全方案，但未设置凭据，启动时会向 stderr 输出警告。
• 如果规范列出了多个方案，则使用顶层 security 列表中的第一个方案（或第一个已定义的方案）。不会应用每个端点的 security 覆盖设置，因此每次调用都会发送密钥。
• OAuth 客户端凭据会以 HTTP Basic 身份验证的方式发送到令牌端点。
• 不内置 OAuth 浏览器登录（授权码流程）。使用提供商的工具获取一次令牌或刷新令牌，然后传入即可。
• 如果提供商会轮换刷新令牌，新令牌只会保存在内存中，因此重启后会丢失。

工作原理

1. 加载规范并解析 $ref 指针。
2. **构建工具：**每个操作都会变成一个 MCP 工具。operationId 是名称，summary 是描述，参数和请求正文则构成输入架构。
3. **调用：**工具调用会发起真实的 HTTP 请求，并返回 HTTP <status>，后接响应正文（截断至 50,000 个字符）。
4. 提供服务：通过 stdio 或 HTTP 使用 JSON-RPC 2.0 提供这些工具。

没有 OpenAPI 规范的 API

许多小型公共 API 只有 HTML 文档。对于这类 API，可以手动编写一个小型规范（参见 sample/animechan.openapi.json，约 35 行，包含 4 个工具），然后用同样的方式运行。

限制

• 仅支持 OpenAPI 3。请先转换 Swagger 2.0 规范。
• 仅支持 JSON 请求正文。不支持文件上传。
• 身份验证：支持 bearer、basic、API 密钥，以及 OAuth2 客户端凭据或刷新令牌。不支持交互式 OAuth 登录，每个 API 只能使用一种方案。
• HTTP 模式使用纯 HTTP（部署时请在前面配置 HTTPS），不支持流式传输、批量请求，也不支持连接到服务器的客户端使用 OAuth（仅支持 MCP_AUTH_TOKEN bearer 令牌）。某些远程客户端可能需要这些功能。
• HTTP 模式使用纯 HTTP（部署时请在前面配置 HTTPS），不支持流式传输、批量请求或 OAuth。某些远程客户端可能需要这些功能。
• 如果远程部署，所有用户都会共用服务器的 IP，因此上游速率限制会影响所有用户。请设置 MCP_AUTH_TOKEN，否则任何找到 URL 的人都能使用你的 API 密钥。

贡献

欢迎提交问题和拉取请求。我们的目标是保持项目小巧易读，因此请将每项新增功能控制在几行代码以内。