openapi

mcp-openapi

将任意 OpenAPI/Swagger 规范转换为 MCP 工具，让 Claude 和其他 AI 助手能够调用你的 REST API。

将 mcp-openapi 指向任意 OpenAPI 3.x 或 Swagger 2.0 规范 URL，它就会自动生成 Model Context Protocol (MCP) 工具。无需代码生成、配置文件或样板代码。几秒钟内，你的 AI 助手就能获得可调用的工具，覆盖每个 API 端点。

---

快速开始

1. 运行（无需安装）：

npx mcp-openapi --spec https://petstore3.swagger.io/api/v3/openapi.json

2. 将其添加到 Claude Desktop（claude_desktop_config.json）：

{
  "mcpServers": {
    "petstore": {
      "command": "npx",
      "args": [
        "mcp-openapi",
        "--spec", "https://petstore3.swagger.io/api/v3/openapi.json"
      ]
    }
  }
}

3. 让 Claude 使用它：

“列出商店中所有可用的宠物”

Claude 会看到 find_pets_by_status、get_pet_by_id、add_pet 等 MCP 工具，并直接调用它们。

---

为什么选择 mcp-openapi？

大多数 MCP 到 API 的桥接工具都要求你手动编写工具定义，或根据规范生成代码。mcp-openapi 则省去了这些步骤。

功能	mcp-openapi	手写 MCP 服务	通用 HTTP 工具
零配置设置	是	否	部分支持
OpenAPI 3.x + Swagger 2.0	是	不适用	不适用
扁平参数架构（针对大模型优化）	是	手动处理	否
根据 operationId 智能命名工具	是	手动处理	否
身份验证（API key、Bearer、OAuth2）	内置	自行实现	自行实现
指数退避重试	内置	自行实现	自行实现
为大模型上下文截断响应	内置	自行实现	否

扁平参数架构是其关键优势。mcp-openapi 不会传递嵌套 JSON 对象（大模型经常会错误处理这些对象），而是将路径、查询、标头和正文参数展平为单个对象。这能大幅提高工具调用的准确性。

---

工作原理

OpenAPI/Swagger Spec          mcp-openapi               AI Assistant
     (URL or file)                                      (Claude, etc.)
          |                         |                         |
          |   1. Parse & validate   |                         |
          |------------------------>|                         |
          |                         |                         |
          |   2. Generate MCP tools |                         |
          |   (one per endpoint)    |                         |
          |------------------------>|                         |
          |                         |                         |
          |                         |   3. Register tools     |
          |                         |   via stdio transport   |
          |                         |------------------------>|
          |                         |                         |
          |                         |   4. AI calls a tool    |
          |                         |<------------------------|
          |                         |                         |
          |   5. Build & execute    |                         |
          |   HTTP request          |                         |
          |<------------------------|                         |
          |                         |                         |
          |   6. Return truncated   |                         |
          |   response to AI        |                         |
          |------------------------>|------------------------>|

每个 API 端点都会变成一个 MCP 工具：

• 工具名称取自 operationId（转换为 snake_case），或根据 method + path 生成
• 参数会展平为单个输入架构（合并路径、查询、标头和正文参数）
• 响应会截断至约 50KB，以符合大模型上下文限制
• 错误（429、5xx）会触发指数退避自动重试（最多重试 3 次）

---

Claude Desktop 集成

编辑配置文件，即可将任意 API 添加到 Claude Desktop：

位置：

• macOS：~/Library/Application Support/Claude/claude_desktop_config.json
• Windows：%APPDATA%\Claude\claude_desktop_config.json

公共 API（无需身份验证）

{
  "mcpServers": {
    "petstore": {
      "command": "npx",
      "args": [
        "mcp-openapi",
        "--spec", "https://petstore3.swagger.io/api/v3/openapi.json"
      ]
    }
  }
}

使用 Bearer Token 的 API

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": [
        "mcp-openapi",
        "--spec", "https://raw.githubusercontent.com/github/rest-api-description/main/descriptions/api.github.com/api.github.com.json",
        "--auth-type", "bearer",
        "--auth-token", "$GITHUB_TOKEN",
        "--prefix", "github",
        "--include", "listReposForAuthenticatedUser,getRepo,listIssues,createIssue"
      ],
      "env": {
        "GITHUB_TOKEN": "ghp_your_token_here"
      }
    }
  }
}

使用 API Key 的 API

{
  "mcpServers": {
    "weather": {
      "command": "npx",
      "args": [
        "mcp-openapi",
        "--spec", "https://api.weather.example.com/openapi.json",
        "--auth-type", "api-key",
        "--auth-name", "X-API-Key",
        "--auth-value", "$WEATHER_API_KEY",
        "--auth-in", "header"
      ],
      "env": {
        "WEATHER_API_KEY": "your_key_here"
      }
    }
  }
}

---

CLI 参考

npx mcp-openapi --spec <url-or-path> [options]

常规选项

选项	短选项	默认值	描述
--spec <url|path>	-s	必需	OpenAPI 规范 URL 或本地文件路径
--config <path>	-c		JSON 配置文件路径
--base-url <url>		来自规范	覆盖 API 基础 URL
--prefix <name>			所有工具名称的前缀（例如，github -> github_list_repos）
--include <patterns>		全部	以逗号分隔的要包含的 operationId
--exclude <patterns>		无	以逗号分隔的要排除的 operationId
--timeout <ms>		30000	HTTP 请求超时时间，单位为毫秒
--max-retries <n>		3	收到 429/5xx 响应时的最大重试次数
--header <name:value>	-H		自定义标头（可重复指定）
--transport <type>		stdio	传输类型：stdio 或 sse
--port <n>		3000	SSE 传输端口
--help	-h		显示帮助
--version	-v		显示版本
--license-key <key>			Pro 许可证密钥（或 $MCP_OPENAPI_LICENSE_KEY 环境变量）
--server <selector>		0	按索引、部分 URL 或完整 URL 选择 API 服务
--no-doc-warnings			启动时不显示文档质量警告
--dynamic-discovery		自动（100+）	为大型 API 启用动态工具发现

身份验证选项

Bearer 令牌：

选项	描述
--auth-type bearer	使用 Bearer 令牌身份验证
--auth-token <token>	令牌值（支持 $ENV_VAR 语法）

API 密钥：

选项	描述
--auth-type api-key	使用 API 密钥身份验证
--auth-name <name>	标头或查询参数名称
--auth-value <value>	API 密钥值（支持 $ENV_VAR 语法）
--auth-in <header|query>	密钥的发送位置（默认：header）

OAuth2 客户端凭据：

选项	描述
--auth-type oauth2	使用 OAuth2 客户端凭据流程
--auth-client-id <id>	OAuth2 客户端 ID
--auth-client-secret <secret>	OAuth2 客户端密钥
--auth-token-url <url>	令牌端点 URL
--auth-scopes <scopes>	以逗号分隔的权限范围

---

CLI 示例

# Basic usage with a remote spec
npx mcp-openapi --spec https://petstore3.swagger.io/api/v3/openapi.json

# Local YAML spec with Bearer auth
npx mcp-openapi --spec ./api.yaml --auth-type bearer --auth-token '$API_KEY'

# Filter to specific endpoints with a prefix
npx mcp-openapi --spec ./api.json --prefix myapi --include 'listUsers,getUser'

# Override base URL (useful for local dev)
npx mcp-openapi --spec https://api.example.com/openapi.json --base-url http://localhost:3000

# Add custom headers
npx mcp-openapi --spec ./api.json -H 'X-Custom: value' -H 'X-Another: value2'

# Use a JSON config file
npx mcp-openapi --config ./mcp-config.json

# Select staging server
npx mcp-openapi --spec ./api.json --server staging

# Large API with dynamic discovery
npx mcp-openapi --spec https://api.stripe.com/openapi.json --dynamic-discovery

配置文件格式

除了使用 CLI 标志外，你还可以使用 JSON 配置文件：

{
  "spec": "https://api.example.com/openapi.json",
  "prefix": "myapi",
  "include": ["listUsers", "getUser", "createUser"],
  "auth": {
    "type": "bearer",
    "token": "$API_TOKEN"
  },
  "timeout": 15000,
  "maxRetries": 2,
  "headers": {
    "X-Custom-Header": "value"
  }
}

CLI 参数的优先级高于配置文件中的值。

---

支持的规范

格式	版本	文件类型
OpenAPI	3.0.x, 3.1.x	.json、.yaml、.yml
Swagger	2.0	.json、.yaml、.yml

规范可以从以下位置加载：

• 远程 URL（https://...）
• 本地文件路径（./api.yaml、/absolute/path/spec.json）

---

v0.3.0 功能

文档质量警告

启动时，mcp-openapi 会检查每个工具的文档质量。如果端点的描述过于简略（少于 50 个字符），你会看到警告：

[mcp-openapi] WARN: Doc quality: 11 of 47 tools have sparse documentation (<50 chars)
[mcp-openapi] WARN:   Affected: getUser, createOrder, deleteItem, updateCart, listTags, ...
[mcp-openapi] WARN:   LLM accuracy may be reduced for these endpoints.

这有助于你识别哪些 API 端点可能导致大模型的工具调用准确率较低。使用 --no-doc-warnings 可关闭警告。

服务筛选

OpenAPI 规范可以定义多个服务（生产、预发布、开发）。选择要使用的服务：

# Use first server (default behavior)
mcp-openapi --spec api.json --server 0

# Match by URL keyword
mcp-openapi --spec api.json --server prod

# Exact URL
mcp-openapi --spec api.json --server https://api.example.com/v2

如果选择器不匹配，你会看到所有可用服务的列表。

动态工具发现

对于包含 100+ 个端点的大型 API，一次性注册所有工具可能会占用过多大模型上下文。动态发现通过改为注册 3 个元工具来解决此问题：

元工具	描述
search_operations(query)	按名称、描述和标签中的关键词搜索工具
list_by_tag(tag?)	按 OpenAPI 标签浏览工具，或列出所有标签
get_tool_details(tool_name)	获取特定工具的完整参数架构

大模型通过这些元工具探索 API，然后按名称调用特定端点。

# Explicit opt-in
mcp-openapi --spec large-api.json --dynamic-discovery

# Auto-enabled when spec has 100+ endpoints
mcp-openapi --spec https://api.github.com/openapi.json

也可以通过配置文件设置：

{
  "spec": "https://api.stripe.com/openapi.json",
  "dynamicDiscovery": true,
  "auth": { "type": "bearer", "token": "$STRIPE_KEY" }
}

---

Pro 功能（v0.2.0+）

mcp-openapi 提供可选的 Pro 功能，适用于团队和高级用户，需使用许可证密钥启用。

自定义响应转换

在 API 响应到达大模型之前，使用 JMESPath 表达式对其进行整形，以减少令牌用量并提高准确性：

{
  "spec": "https://api.github.com/openapi.json",
  "licenseKey": "$MCP_OPENAPI_LICENSE_KEY",
  "transforms": {
    "list_repos": "data[].{name: name, stars: stargazers_count, url: html_url}",
    "list_*": "data[].{id: id, name: name}"
  }
}

智能响应处理

Pro 不会在响应超过 50KB 时直接截断，而是启用智能截断：

• 数组切片：大型数组显示前 N 项及元数据（"showing 10 of 847 items"）
• 深度裁剪：超过可配置深度的深层嵌套对象会被摘要化
• 保留结构：你始终能看到数据的结构，不会遇到 JSON 被截断一半的情况

{
  "spec": "./api.json",
  "licenseKey": "$MCP_OPENAPI_LICENSE_KEY",
  "response": {
    "maxLength": 50000,
    "arraySliceSize": 10,
    "maxDepth": 4
  }
}

即将推出

• 多 API 组合 — 在一个 MCP 会话中加载多个 OpenAPI 规范
• 使用情况分析 — 跟踪工具调用、延迟和错误率

对 Pro 感兴趣？为仓库点星，并提出问题以获取早期访问权限。

---

编程方式使用

你也可以在自己的 MCP 服务中将 mcp-openapi 用作库：

import { createServer } from 'mcp-openapi';

const { server, tools, spec } = await createServer({
  spec: 'https://petstore3.swagger.io/api/v3/openapi.json',
  prefix: 'petstore',
  auth: {
    type: 'bearer',
    token: process.env.API_TOKEN,
  },
});

console.log(`Loaded ${tools.length} tools from ${spec.info.title}`);

---

要求

• Node.js 18 或更高版本
• OpenAPI 3.x 或 Swagger 2.0 规范（URL 或本地文件）

---

参与贡献

欢迎贡献。以下是开始的方法：

git clone https://github.com/Docat0209/mcp-openapi.git
cd mcp-openapi
pnpm install
pnpm test
pnpm build

提交 PR 前：

1. 为新功能添加测试
2. 运行 pnpm lint 并修复所有问题
3. 提交消息遵循 Conventional Commits 规范

---

相关项目

• graphql-to-mcp — 为 GraphQL API 提供相同的零配置方案

许可证

MIT

---

关键词

mcp, model-context-protocol, openapi, swagger, claude, ai, llm, api, tools, rest-api, ai-tools, mcp-server