OpenAPI 至 MCP 生成器 (openapi-mcp-generator)

根据 OpenAPI 规范生成 模型上下文协议 (MCP) 服务器。

此 CLI 工具可自动构建与 MCP 兼容的代理服务器，将请求转发至现有的 REST API，从而使 AI 代理及其他 MCP 客户端能够通过您选择的传输方式无缝地与您的 API 进行交互。

---

✨ 功能

• 🔧 OpenAPI 3.0 支持：将任何 OpenAPI 3.0 及以上版本的规范转换为与 MCP 兼容的服务器。
• 🔁 代理行为：在验证请求结构和安全性的同时，将调用代理到您的原始 REST API。
• 🔐 身份验证支持：通过环境变量支持 API 密钥、Bearer 令牌、Basic 认证和 OAuth2。
• 🧪 Zod 验证：根据 OpenAPI 定义自动生成 Zod 模式，用于运行时输入验证。
• ⚙️ 类型化服务器：输出完全类型化的、易于维护的 TypeScript 代码。
• 🔌 多种传输方式：可通过标准输入输出、Hono 的 SSE 或 StreamableHTTP 进行通信。
• 🧰 项目脚手架：生成包含 tsconfig.json、package.json 和入口文件的完整 Node.js 项目。
• 🧪 内置 HTML 测试客户端：可在浏览器中以可视化方式测试 API 交互（适用于基于 Web 的传输）。

---

🚀 安装

npm install -g openapi-mcp-generator

您也可以使用 yarn global add openapi-mcp-generator 或 pnpm add -g openapi-mcp-generator

---

🛠 使用方法

# 生成一个 stdio 传输的 MCP 服务器
openapi-mcp-generator --input path/to/openapi.json --output path/to/output/dir

# 生成一个带有 SSE 的 Web MCP 服务器
openapi-mcp-generator --input path/to/openapi.json --output path/to/output/dir --transport=web --port=3000

# 生成一个 StreamableHTTP 传输的 MCP 服务器
openapi-mcp-generator --input path/to/openapi.json --output path/to/output/dir --transport=streamable-http --port=3000

CLI 选项

选项	别名	描述	默认
--input	-i	OpenAPI 规范的路径或 URL（YAML 或 JSON）	必填
--output	-o	生成的 MCP 项目的输出目录	必填
--server-name	-n	MCP 服务器的名称（package.json:name）	OpenAPI 标题或 mcp-api-server
--server-version	-v	MCP 服务器的版本（package.json:version）	OpenAPI 版本或 1.0.0
--base-url	-b	API 请求的基础 URL。如果 OpenAPI 的 servers 缺失或不明确，则必须提供。	尽可能自动检测
--transport	-t	传输模式："stdio"（默认）、"web" 或 "streamable-http"	"stdio"
--port	-p	基于 Web 的传输所使用的端口	3000
--default-include		x-mcp 过滤的默认行为。接受 true 或 false（不区分大小写）。true 表示默认包含，false 表示默认排除。	true
--force		在不进行确认的情况下覆盖输出目录中的现有文件	false

📦 程序化 API

您也可以在自己的 Node.js 应用程序中以编程方式使用此包：

import { getToolsFromOpenApi } from 'openapi-mcp-generator';

// 从 OpenAPI 规范中提取 MCP 工具定义
const tools = await getToolsFromOpenApi('./petstore.json');

// 带有选项
const filteredTools = await getToolsFromOpenApi('https://example.com/api-spec.json', {
  baseUrl: 'https://api.example.com',
  dereference: true,
  excludeOperationIds: ['deletePet'],
  filterFn: (tool) => tool.method.toLowerCase() === 'get',
});

有关程序化 API 的完整文档，请参阅 PROGRAMMATIC_API.md。

---

🧱 项目结构

生成的项目包括：

<output_directory>/
├── .gitignore
├── package.json
├── tsconfig.json
├── .env.example
├── src/
│   ├── index.ts
│   └── [与传输方式相关的文件]
└── public/          # 用于基于 Web 的传输
    └── index.html   # 测试客户端

核心依赖项：

• @modelcontextprotocol/sdk - MCP 协议实现
• axios - 用于 API 请求的 HTTP 客户端
• zod - 运行时验证
• json-schema-to-zod - 将 JSON Schema 转换为 Zod
• 传输特定的依赖项（Hono、uuid 等）

---

📡 传输模式

Stdio（默认）

通过标准输入输出与 MCP 客户端通信。非常适合本地开发或与 LLM 工具集成。

带有 SSE 的 Web 服务器

启动一个功能齐全的 HTTP 服务器，具备以下特性：

• 服务器发送事件 (SSE)，用于双向消息传递
• REST 端点，用于客户端到服务器的通信
• 浏览器内测试客户端 UI
• 多连接支持
• 基于轻量级 Hono 框架构建

StreamableHTTP

实现 MCP 的 StreamableHTTP 传输，提供以下功能：

• 基于 HTTP POST 请求的状态感知 JSON-RPC
• 使用 HTTP 头部进行会话管理
• 正确的 HTTP 响应状态码
• 内置错误处理
• 与 MCP StreamableHTTPClientTransport 兼容
• 浏览器内测试客户端 UI
• 基于轻量级 Hono 框架构建

传输方式对比

特性	标准输入输出	Web (SSE)	可流式 HTTP
协议	基于标准输入输出的 JSON-RPC	基于 SSE 的 JSON-RPC	基于 HTTP 的 JSON-RPC
连接	长连接	长连接	请求/响应
双向通信	是	是	是（有状态）
多客户端支持	否	是	是
浏览器兼容性	否	是	是
防火墙友好性	否	是	是
负载均衡	否	有限	是
状态码	否	有限	完整 HTTP 状态码
头信息	否	有限	完整 HTTP 头
测试客户端	否	是	是

---

🔐 认证用环境变量

在您的环境中配置认证凭据：

认证类型	变量格式
API 密钥	API_KEY_<SCHEME_NAME>
Bearer 令牌	BEARER_TOKEN_<SCHEME_NAME>
Basic 认证	BASIC_USERNAME_<SCHEME_NAME>, BASIC_PASSWORD_<SCHEME_NAME>
OAuth2	OAUTH_CLIENT_ID_<SCHEME_NAME>, OAUTH_CLIENT_SECRET_<SCHEME_NAME>, OAUTH_SCOPES_<SCHEME_NAME>

---

🔎 使用 OpenAPI 扩展筛选端点

您可以使用供应商扩展标志 x-mcp 来控制哪些操作作为 MCP 工具公开。此扩展在根、路径和操作级别均受支持。默认情况下，端点会被包含，除非被显式排除。

• 扩展：x-mcp: true | false
• 默认值：true（默认包含）
• 优先级：操作 > 曲线 > 根（第一个非未定义值生效）
• CLI 选项：--default-include false 可将默认行为更改为默认排除。

示例：

# 可选的根级默认值
x-mcp: true

paths:
  /pets:
    x-mcp: false # 排除 /pets 下的所有操作
    get:
      x-mcp: true # 无论如何都包含此操作

  /users/{id}:
    get:
      # 没有 x-mcp -> 默认包含

这使用了标准的 OpenAPI 扩展（x-… 字段）。有关详细信息，请参阅 OpenAPI 扩展指南。

注意：x-mcp 必须是布尔值或字符串 "true"/"false"（不区分大小写）。其他值将被忽略，以遵循更高优先级或默认行为。

---

▶️ 运行生成的服务器

cd path/to/output/dir
npm install

# 以标准输入输出模式运行
npm start

# 以 Web 服务器模式运行
npm run start:web

# 以可流式 HTTP 模式运行
npm run start:http

测试基于 Web 的服务器

对于 Web 和可流式 HTTP 传输方式，会自动生成一个基于浏览器的测试客户端：

1. 使用相应的命令启动服务器
2. 在浏览器中打开 http://localhost:<port>
3. 使用测试客户端与您的 MCP 服务器交互

---

⚠️ 系统要求

• Node.js v20 或更高版本

---

星标历史

🤝 贡献

欢迎贡献！

1. 分支仓库
2. 创建功能分支：git checkout -b feature/amazing-feature
3. 运行 npm run format.write 来格式化代码
4. 提交更改：git commit -m "添加精彩功能"
5. 推送并打开拉取请求

📌 仓库：github.com/harsha-iiiv/openapi-mcp-generator

---

📄 许可证

MIT 许可证 — 详情请参阅 LICENSE 文件。

openapi-mcp-generator 快速上手指南

openapi-mcp-generator 是一个命令行工具，可自动将 OpenAPI 3.0+ 规范转换为兼容 Model Context Protocol (MCP) 的服务器。它允许 AI 代理通过标准输入输出（stdio）、SSE 或 StreamableHTTP 无缝调用现有的 REST API。

环境准备

在开始之前，请确保您的开发环境满足以下要求：

• Node.js: 版本 v20 或更高。
  • 检查版本：node -v
  • 如未安装，请访问 Node.js 官网 下载。
• 包管理器: npm、yarn 或 pnpm（任选其一）。
• OpenAPI 规范文件: 准备好您的 API 定义文件（.json 或 .yaml 格式）。

国内加速建议：如果 npm 安装缓慢，建议配置淘宝镜像源：

npm config set registry https://registry.npmmirror.com

安装步骤

使用 npm 全局安装该工具：

npm install -g openapi-mcp-generator

如果您使用 yarn 或 pnpm，也可以使用以下命令：

yarn global add openapi-mcp-generator
# 或
pnpm add -g openapi-mcp-generator

基本使用

1. 生成 MCP 服务器（默认 stdio 模式）

这是最简单的用法，将 OpenAPI 文件转换为本地可运行的 MCP 服务器代码。

openapi-mcp-generator --input path/to/openapi.json --output path/to/output/dir

• --input (-i): 指向您的 OpenAPI 规范文件路径或 URL。
• --output (-o): 指定生成项目的输出目录。

2. 生成 Web 服务器（SSE 模式）

如果您希望通过 HTTP/SSE 让浏览器或远程客户端连接，可指定 web 传输模式：

openapi-mcp-generator --input path/to/openapi.json --output path/to/output/dir --transport=web --port=3000

3. 运行生成的服务

进入生成的目录并安装依赖，然后启动服务：

cd path/to/output/dir
npm install

# 运行 stdio 模式（适合本地 LLM 工具集成）
npm start

# 运行 Web 模式（适合浏览器测试或远程连接）
npm run start:web

# 运行 StreamableHTTP 模式
npm run start:http

测试提示：对于 web 和 streamable-http 模式，启动后直接在浏览器访问 http://localhost:<port>（例如 http://localhost:3000），即可使用内置的可视化测试客户端与您的 MCP 服务器交互。