使用说明

mcp openapi

将任何OpenAPI/Swagger规范转换为MCP工具，以便Claude和其他AI助手可以调用您的REST API。

点 mcp-openapi 在任何OpenAPI 3.x或Swagger 2.0规范URL上，它都会生成模型上下文协议（MCP）自动工具。没有代码生成，没有配置文件，没有样板。你的人工智能助手在几秒钟内为每个API端点获得可调用的工具。

快速开始

1.运行它 （无需安装）：

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

2.将其添加到克劳德桌面 (claude_desktop_config.json):

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

3.让克劳德使用它：

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

Claude看到了MCP工具，如 find_pets_by_status, get_pet_by_id, add_pet 并直接给他们打电话。

为什么选择mcp openapi？

大多数MCP-to-API桥接需要手工编写工具定义或根据规范生成代码。 mcp-openapi 跳过所有这些。

功能	mcp-openapi	手写mcp服务器	通用HTTP工具
零配置设置	是	否	部分
OpenAPI 3.x+Swagger 2.0	是	不适用	不适用
平面参数模式（LLM优化）	是	手动	否
从操作ID命名智能工具	是	手动	否
Auth（API密钥，Bearer，OAuth2）	内置	自己动手	自己动手
使用指数回退重试	内置	DIY	DIY
LLM上下文的响应截断	内置	DIY	否

平面参数模式 是关键的差异化因素。与其传递嵌套的JSON对象（LLM经常出错）， mcp-openapi 将路径、查询、标头和正文参数扁平化为单个扁平对象。这大大提高了工具调用的准确性。

运作原理

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，以保持在LLM上下文限制内
错误（429，5xx）触发指数回退的自动重试（最多3次重试）

Claude桌面集成

通过编辑配置文件将任何API添加到Claude Desktop：

地点：

macOS： ~/Library/Application Support/Claude/claude_desktop_config.json
窗户： %APPDATA%\Claude\claude_desktop_config.json

公共API（无授权）

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

带有承载令牌的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密钥的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>`		all	要包含的逗号分隔操作ID
`--exclude <patterns>`		none	要排除的逗号分隔操作ID
`--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` env）
`--server <selector>`		`0`	按索引、部分URL或确切URL选择API服务器
`--no-doc-warnings`			启动时抑制文档质量警告
`--dynamic-discovery`		自动（100+）	为大型API启用动态工具发现

身份验证选项

持有者代币：

选项	描述
`--auth-type 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

配置文件格式

您可以使用JSON配置文件代替CLI标志：

{
  "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端点可能会导致LLM工具调用精度差。抑制与 --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，一次注册所有工具可能会淹没LLM的上下文。动态发现通过注册3个元工具来解决这个问题：

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

LLM通过这些元工具探索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" }
}

专业功能（v0.2.0+）

mcp-openapi 包括团队和高级用户的可选Pro功能，由许可证密钥控制。

自定义响应转换

形状API响应 JMESPath 表达式在到达LLM之前——减少令牌使用并提高准确性：

{
  "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组合 --将多个OpenAPI规范加载到一个MCP会话中
使用情况分析 --跟踪工具调用、延迟和错误率

对Pro感兴趣？明星回购和打开一个问题以便尽早进入。

程序化使用

您还可以使用 mcp-openapi 作为您自己的MCP服务器中的库：

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之前：

为新功能添加测试
跑 pnpm lint 并修复任何问题
跟随常规提交用于提交消息

许可证

麻省理工学院

关键词

mcp、模型上下文协议、openapi、swagger、claude、ai、llm、api、工具、restapi、ai工具、mcp服务器

OpenAPI转换工具

使用说明

mcp openapi

快速开始

为什么选择mcp openapi？

运作原理

Claude桌面集成

公共API（无授权）

带有承载令牌的API

带API密钥的API

CLI参考

常规选项

身份验证选项

CLI示例

配置文件格式

支持的规格

v0.3.0功能

文件质量警告

服务器筛选

动态工具发现

专业功能（v0.2.0+）

自定义响应转换

智能响应处理

即将推出

程序化使用

需求

贡献

相关

许可证

关键词

使用说明

mcp openapi

快速开始

为什么选择mcp openapi？

运作原理

Claude桌面集成

公共API（无授权）

带有承载令牌的API

带API密钥的API

CLI参考

常规选项

身份验证选项

CLI示例

配置文件格式

支持的规格

v0.3.0功能

文件质量警告

服务器筛选

动态工具发现

专业功能（v0.2.0+）

自定义响应转换

智能响应处理

即将推出

程序化使用

需求

贡献

相关

许可证

关键词

相关 MCP

思维工具服务器

Obsidian笔记搜索服务

APISIX MCP服务器

n8n工作流管理服务

模型上下文协议服务器

Markdown内容交付网络