MCP Openapi (Docat0209)

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 跳过所有这些。

平面参数模式 是关键的差异化因素。与其传递嵌套的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    |
          |                         ||------------------------>|

每个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  [options]

常规选项

身份验证选项

持有者代币：

API密钥：

OAuth2客户端凭据：

______________________________________________________________________

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参数优先于配置文件值。

______________________________________________________________________

支持的规格

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

• 远程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 ( 对Pro感兴趣？明星回购和 [打开一个问题](https://github.com/Docat0209/mcp-openapi/issues) 以便尽早进入。

______________________________________________________________________

## 程序化使用

您还可以使用 `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之前：

1. 为新功能添加测试
1. 跑 `pnpm lint` 并修复任何问题
1. 跟随 [常规提交](https://www.conventionalcommits.org/) 用于提交消息

______________________________________________________________________

## 相关

- [从graphql到mcp](https://www.npmjs.com/package/graphql-to-mcp) --GraphQL API采用相同的零配置方法

## 许可证

麻省理工学院

______________________________________________________________________

## 关键词

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