OpenAPI to MCP Generator (openapi-mcp-generator)

OpenAPI 到 MCP 生成器（openapi-mcp-generator）

openapi-mcp-generator 是一个免费的 MIT 许可命令行工具和库，可将 OpenAPI 3.x 规范转换为可直接运行的 Model Context Protocol（MCP） 服务，支持 stdio、SSE、Streamable HTTP 或 Cloudflare Workers。 生成的 TypeScript 代码归你所有；在任何请求发送到你的 API 之前，工具输入都会经过 JSON Schema 验证。

文档 · 快速入门 · 浏览器体验区 · 更新日志

npx openapi-mcp-generator --input ./openapi.json --output ./my-mcp

---

✨ 功能特性

• 🔧 支持 OpenAPI 3.x：将任何 OpenAPI 3.0 或 3.1 规范转换为兼容 MCP 的服务（请先转换 Swagger 2.0）。
• 🔁 代理行为：代理对原始 REST API 的调用，同时验证请求结构和安全性。
• 🔐 身份验证支持：支持通过环境变量设置 API 密钥、Bearer 令牌、Basic 身份验证和 OAuth2；缺少必需凭据时将拒绝调用。
• 🧪 JSON Schema 验证：根据每个工具的 JSON Schema 2020-12 输入架构验证参数（不生成代码，也不使用 eval）。
• 🏷️ 注解和结构化输出：工具带有标题，以及只读、破坏性和幂等性提示；JSON 对象响应将作为 structuredContent 返回（还可声明 outputSchema）。
• ⚙️ 类型化服务：输出完全类型化、易于维护的 TypeScript 代码。
• 🔌 多种传输方式：支持通过 stdio、基于 Hono 的 SSE、StreamableHTTP 或可部署的 Cloudflare Worker 通信。
• 🧰 项目脚手架：生成完整的 Node.js 项目，其中包含 tsconfig.json、package.json 和入口文件。
• 🧪 内置 HTML 测试客户端：在浏览器中直观地测试 API 交互（适用于基于 Web 的传输方式）。

---

🚀 安装

npm install -g openapi-mcp-generator

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

---

⬆️ 升级到 5.0

5.0 基于 MCP TypeScript SDK v2 生成服务，并支持 MCP 2026-07-28 及 2025 年前后推出的客户端。生成的项目有所变化，请谨慎升级：

1. 提交生成的项目，然后使用相同的标志重新生成：npx openapi-mcp-generator@5 -i ./openapi.json -o ./my-mcp --force。--force 会覆盖生成的文件，包括你所做的修改。
2. 使用 Node.js 22.19 或更高版本运行生成器（生成的项目需要 Node.js 22 或更高版本），然后运行 npm install。@modelcontextprotocol/sdk 已替换为 @modelcontextprotocol/server（^2.4.0），zod、json-schema-to-zod、dotenv 和 uuid 已替换为 @cfworker/json-schema。
3. 更新自定义代码，从 @modelcontextprotocol/server 导入（stdio 辅助工具从 @modelcontextprotocol/server/stdio 导入）。
4. Streamable HTTP 和 Worker 服务均为无状态：没有 mcp-session-id，且对 /mcp 执行 GET 和 DELETE 会返回 405。通过 POST 调用工具不受影响。
5. 缺少上游凭据时现在会安全失败，并报错指出需要设置的变量；设置 MCP_ALLOW_MISSING_CREDENTIALS=true 可恢复旧行为。
6. 未知工具名称现在会触发 JSON-RPC -32602 错误。整数仍为整数，readOnly 属性会从请求输入中移除，且不再注入架构默认值。
7. 不接受 Swagger 2.0 规范：请使用 npx swagger2openapi swagger.json -o openapi.json 转换。
8. 凭据变量、Worker 密钥名称、--inbound-auth、--header-passthrough 和 MCP_ALLOWED_ORIGINS 均未改变。

还没准备好？使用 npx openapi-mcp-generator@4 继续使用 4.x。完整说明：CHANGELOG.md。

---

🛠 用法

# Generate an MCP server (stdio)
openapi-mcp-generator --input path/to/openapi.json --output path/to/output/dir

# Generate an MCP web server with SSE
openapi-mcp-generator --input path/to/openapi.json --output path/to/output/dir --transport=web --port=3000

# Generate an MCP StreamableHTTP server
openapi-mcp-generator --input path/to/openapi.json --output path/to/output/dir --transport=streamable-http --port=3000

# Generate a deployable Cloudflare Worker MCP server
openapi-mcp-generator --input path/to/openapi.json --output path/to/output/dir --transport=cloudflare-worker

examples/ 文件夹中包含使用 5.0 生成的 Swagger Petstore 示例，分别用于 stdio（petstore-mcp）、web（pet-store-sse）和 StreamableHTTP（pet-store-streamable-http）。

CLI 选项

选项	别名	描述	默认值
--input	-i	OpenAPI 规范（YAML 或 JSON）的路径或 URL	必填
--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" 或 "cloudflare-worker"	"stdio"
--port	-p	Web 传输模式使用的端口	3000
--default-include		x-mcp 筛选的默认行为。接受 true 或 false（不区分大小写）。true = 默认包含，false = 默认排除。	true
--allow-external-refs		允许解析规范中的外部 http(s) $ref 引用。默认禁用，以防解析期间发生 SSRF。	false
--max-tool-name-length		生成的工具名称的最大长度（Claude Desktop 限制为 64）。超出长度的名称会被截断，并附加哈希后缀。	64
--header-passthrough		以逗号分隔的入站标头名称，转发至上游 API（web、streamable-http、cloudflare-worker）。支持按用户使用 API 密钥。	(无)
--inbound-auth		HTTP 传输的入站身份验证：none 或 bearer。使用 bearer 时，客户端必须发送 Authorization: Bearer <token>（MCP_AUTH_TOKEN）。	none
--insecure	-k	在生成的服务中允许不安全的 HTTPS 连接（跳过 TLS 证书验证）。	false
--generate-lib		生成库式输出：导出 main() 而非自动调用它，并省略信号/清理逻辑。	false
--custom-auth		生成可编辑的 src/auth.ts 钩子（applyCustomAuth），在内置身份验证前调用；返回 true 可跳过内置身份验证。	false
--oauth-creds-in-body		在令牌请求正文中发送 OAuth2 客户端凭据，而不是通过 Basic Authorization 标头发送。	false
--include-tags		以逗号分隔的标签：仅生成带有其中任一标签的操作（不区分大小写）。	(全部)
--exclude-tags		以逗号分隔的标签：跳过带有其中任一标签的操作。排除项优先于包含项。	(无)
--include-operations		以逗号分隔的 operationId 或工具名称，用于指定要生成的内容。与 --include-tags 取并集。	(全部)
--exclude-operations		以逗号分隔的 operationId 或工具名称，用于指定要跳过的内容。排除项优先于包含项。	(无)
--output-schema		根据 2xx JSON 响应架构（仅对象）声明每个工具的 outputSchema，并拒绝与其不匹配的响应。	false
--force		无需确认即可覆盖输出目录中的现有文件	false

在运行时配置 API 基础 URL： 生成的服务会从环境变量（.env）中读取 API_BASE_URL，并覆盖从 OpenAPI servers 列表中写入的值。端口依次取自 --port、PORT 环境变量，最后回退到 3000。

操作和路径级别的服务： 操作的 servers[0] 优先于其路径项的服务， 路径项的服务优先于根服务；服务器变量使用其默认值。即使设置了 API_BASE_URL， 也会使用绝对操作或路径服务；相对服务则会基于当前基础 URL 解析（"v2" 会追加路径段，"/v2" 会替换路径）。

📦 程序化 API

此软件包还导出了 CLI 使用的解析器，因此你可以在自己的 Node.js 代码中将 OpenAPI 文档转换为 MCP 工具 定义：

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

// From a local file or a URL
const tools = await getToolsFromOpenApi('./petstore.json', { dereference: true });

// With options
const readOnlyPetTools = await getToolsFromOpenApi(
  'https://petstore3.swagger.io/api/v3/openapi.json',
  {
    baseUrl: 'https://petstore3.swagger.io/api/v3',
    dereference: true,
    includeTags: ['pet'],
    excludeOperations: ['deletePet'],
    filterFn: (tool) => tool.annotations?.readOnlyHint === true,
  }
);

for (const tool of readOnlyPetTools) {
  console.log(`${tool.name}: ${tool.method.toUpperCase()} ${tool.pathTemplate}`);
}

getToolsFromOpenApi(spec, options?)

spec 可以是文件路径、http(s) URL，或已解析的 OpenAPIV3.Document。该函数 返回 Promise<McpToolDefinition[]>。不接受 Swagger 2.0 文档；请先转换 （npx swagger2openapi swagger.json -o openapi.json）。

选项	说明	默认值
baseUrl	覆盖规范中 servers 提供的基础 URL
dereference	提取工具前解析 $ref。不启用时，引用的架构将保持未解析状态，并会为每个架构记录一条警告	false
includeTags / excludeTags	仅保留或排除带有这些标签的操作（不区分大小写）
includeOperations / excludeOperations	仅保留或排除这些操作（operationId 或工具名称）。规则与 CLI 标志相同：包含项会合并，排除项优先
excludeOperationIds	排除这些 operationId（较旧的选项，在上述筛选器之后应用）
filterFn	自定义谓词 (tool) => boolean，最后应用
defaultInclude	是否包含没有 x-mcp 扩展的操作	true
allowExternalRefs	允许外部 http(s) $ref。默认关闭，因此解析过程不会被用于 SSRF	false
maxToolNameLength	生成的工具名称最大长度（Claude Desktop 允许 64 个字符）	64

筛选器会在 x-mcp 筛选之后应用。若要自行解析文档，请传入解析结果：

import SwaggerParser from '@apidevtools/swagger-parser';
import type { OpenAPIV3 } from 'openapi-types';
import { getToolsFromOpenApi } from 'openapi-mcp-generator';

const api = (await SwaggerParser.dereference('./openapi.yaml')) as OpenAPIV3.Document;
const tools = await getToolsFromOpenApi(api);

工具定义

interface McpToolDefinition {
  name: string; // unique tool name
  title?: string; // x-mcp-title, else the operation summary
  description: string;
  inputSchema: JSONSchema7 | boolean; // JSON Schema 2020-12 for the tool arguments
  method: string; // get, post, ...
  pathTemplate: string; // e.g. /pet/{petId}
  parameters: OpenAPIV3.ParameterObject[];
  executionParameters: { name: string; in: string }[];
  requestBodyContentType?: string;
  serverUrl?: string; // operation or path-item server, variables resolved
  baseUrl?: string; // set by getToolsFromOpenApi: the baseUrl option or root server, else ''
  securityRequirements: OpenAPIV3.SecurityRequirementObject[];
  operationId: string;
  tags?: string[];
  deprecated?: boolean;
  annotations?: McpToolAnnotations; // readOnlyHint, destructiveHint, idempotentHint, openWorldHint
  outputSchema?: JSONSchema7; // lowest 2xx application/json response, when it is an object
}

inputSchema 会保留 integer 类型，将 example 转换为 examples，并省略 readOnly 属性。注解根据 HTTP 方法生成（GET 和 HEAD 为只读，DELETE 具有破坏性，PUT 和 DELETE 具有幂等性），也可以通过 x-mcp-annotations 按操作覆盖。getToolsFromOpenApi 返回的每个工具都带有 baseUrl：取值依次为 baseUrl 选项、规范的根服务器，否则为空字符串。操作或路径项的服务器会放在 serverUrl 中，并在调用 API 时优先使用。

更多筛选器：

const spec = './petstore.json';

// Only GET operations
await getToolsFromOpenApi(spec, { dereference: true, filterFn: (tool) => tool.method === 'get' });

// Only operations that require authentication
await getToolsFromOpenApi(spec, {
  dereference: true,
  filterFn: (tool) => tool.securityRequirements.length > 0,
});

// Read-only user endpoints, without two specific operations
await getToolsFromOpenApi(spec, {
  dereference: true,
  excludeOperationIds: ['deleteUser', 'updateUser'],
  filterFn: (tool) =>
    tool.pathTemplate.startsWith('/user') && tool.annotations?.readOnlyHint === true,
});

---

🧱 项目结构

生成的项目包含：

<output_directory>/
├── .gitignore
├── package.json
├── tsconfig.json
├── .env.example
├── src/
│   ├── index.ts
│   └── [transport-specific-files]
└── public/          # web and streamable-http: the browser playground
    ├── index.html, playground.js, playground.css, mcp-client.js
    └── playground.config.json

核心依赖：

• @modelcontextprotocol/server - MCP 协议实现（SDK v2）
• @cfworker/json-schema - 验证工具参数的 JSON Schema 2020-12（使用 --output-schema 时还会验证输出）
• axios - 用于 API 请求的 HTTP 客户端
• 特定传输方式的依赖（hono、@hono/node-server）

.env 由 Node 内置的 process.loadEnvFile() 加载；无需依赖 dotenv。

---

📡 传输模式

生成的服务使用 MCP 2026-07-28 协议（无状态请求、server/discover），并继续为使用 initialize 初始化的 2025 年代客户端提供服务，采用 MCP TypeScript SDK v2。由于规范已弃用 HTTP+SSE，web（SSE）传输仍使用 2025 年代协议；新部署建议使用 streamable-http。

Stdio（默认）

通过标准输入/输出与 MCP 客户端通信。适合本地开发或与大模型工具集成。

使用 SSE 的 Web 服务

启动功能完整的 HTTP 服务，提供：

• 用于双向消息传递的服务器发送事件（SSE）
• 用于客户端 → 服务端通信的 REST 端点
• 位于 / 的浏览器 Playground
• 多连接支持
• 使用轻量级 Hono 框架构建

StreamableHTTP

实现 MCP StreamableHTTP 传输，提供：

• 通过 HTTP 传输无状态 JSON-RPC：每个请求都会创建一个全新的服务，因此可在任意负载均衡器后扩展
• 支持 MCP 2026-07-28 和 2025 年代客户端（2025 年代客户端无需会话即可运行；GET 和 DELETE 会返回 405）
• 正确的 HTTP 响应状态码
• 内置错误处理
• 兼容 MCP StreamableHTTPClientTransport
• 位于 / 的浏览器 Playground
• 使用轻量级 Hono 框架构建

Cloudflare Worker

生成完整、可部署的 Cloudflare Workers 项目，通过 /mcp 上的 Streamable HTTP 提供 MCP 服务，并使用 @modelcontextprotocol/server 中的 createMcpHandler（不依赖额外框架）。只需一条命令，即可将其部署到你自己的 Cloudflare 账户：

openapi-mcp-generator --input ./openapi.json --output ./my-mcp-worker --transport cloudflare-worker
cd my-mcp-worker
npm install
npx wrangler secret put API_KEY   # set upstream API secrets (see .dev.vars.example)
npx wrangler deploy               # Wrangler logs into YOUR Cloudflare account and deploys

亮点：

• 无状态，可在免费的 Workers 层运行（无需 Durable Objects 或 KV）。每个请求都会创建一个全新的 MCP 服务。
• 依赖精简：仅需 @modelcontextprotocol/server 和 @cfworker/json-schema，无需额外的 Agent 框架。
• 非机密配置（例如 API_BASE_URL）保存在 wrangler.jsonc 的 vars 中；使用 wrangler secret put 设置密钥，并从 env 绑定读取，绝不会提交到代码库。
• 原生 Workers 运行时：使用全局 fetch（不使用 Node https），并使用 @cfworker/json-schema 根据 JSON Schema 验证参数（不进行代码生成，也不使用 eval）。
• 身份验证会考虑方案类型：API 密钥（请求头／查询参数／Cookie）、HTTP basic／bearer、OpenID Connect 令牌以及 OAuth2 客户端凭据，均从 env 密钥中获取，并遵循 OpenAPI 安全要求语义（参见保护 HTTP 服务）。
• --inbound-auth bearer 使用通过 wrangler secret put MCP_AUTH_TOKEN 设置的令牌保护 /mcp；--header-passthrough 会转发客户端提供的、按用户区分的上游密钥。
• --custom-auth、--port、--insecure、--generate-lib 和 --oauth-creds-in-body 不适用于此目标，会被忽略并显示警告。

本地开发：执行 cp .dev.vars.example .dev.vars，取消注释并填写你要使用的密钥，然后运行 npm run dev（服务地址为 http://localhost:8787/mcp）。可使用 MCP Inspector 连接；也可在 Claude Desktop 中通过 mcp-remote 连接。

Transport Comparison

Feature	stdio	web (SSE)	streamable-http	cloudflare-worker
Protocol	JSON-RPC over stdio	JSON-RPC over SSE	JSON-RPC over HTTP	Streamable HTTP at /mcp
Connection	Persistent	Persistent	Request/response	Request/response
Bidirectional	Yes	Yes	Yes (stateless)	Yes
Multiple clients	No	Yes	Yes	Yes
Browser compatible	No	Yes	Yes	Yes
Firewall friendly	No	Yes	Yes	Yes
Load balancing	No	Limited	Yes	Yes (edge)
Status codes	No	Limited	Full HTTP codes	Full HTTP codes
Headers	No	Limited	Full HTTP headers	Full HTTP headers
Browser playground	No	Yes	Yes	Yes
Hosting	Local	Self-hosted	Self-hosted	Cloudflare (serverless)

---

🔐 用于身份验证的环境变量

在环境中配置身份验证凭据：

身份验证类型	变量格式
API 密钥	API_KEY_<SCHEME_NAME>
Bearer	BEARER_TOKEN_<SCHEME_NAME>
Basic Auth	BASIC_USERNAME_<SCHEME_NAME>, BASIC_PASSWORD_<SCHEME_NAME>
OAuth2	OAUTH_TOKEN_<SCHEME_NAME>，或 OAUTH_CLIENT_ID_<SCHEME_NAME>, OAUTH_CLIENT_SECRET_<SCHEME_NAME>, OAUTH_SCOPES_<SCHEME_NAME>
OpenID	OPENID_TOKEN_<SCHEME_NAME>

对于 OAuth2，OAUTH_TOKEN_<SCHEME_NAME> 是你已有的令牌，适用于所有流程。 否则，服务会获取令牌：如果该方案支持客户端凭据流程，则使用客户端 ID 和密钥；如果仅支持密码流程，则使用 OAUTH_USERNAME_<SCHEME_NAME> 和 OAUTH_PASSWORD_<SCHEME_NAME>（并在令牌端点需要时提供客户端 ID，以及机密客户端的密钥）。

当某个操作列出多个安全要求时，会使用其所有方案均已配置的第一个要求。如果没有任何要求可以满足（转发的 --header-passthrough 标头也算） 且该操作不允许使用空 {} 要求匿名访问，工具会默认拒绝：不会调用 API，并会返回说明需要设置什么的错误，例如 Missing credentials for 'getPet': set API_KEY_PETSTORE_AUTH.。设置 MCP_ALLOW_MISSING_CREDENTIALS=true（对于 Workers，此项为 Worker 变量），即可改为不带凭据发送此类请求。除非 OAUTH_SCOPES_<SCHEME_NAME> 覆盖操作的作用域，否则 OAuth2 令牌会根据操作的作用域请求。Cloudflare Worker 目标会从名为 <SCHEME_NAME>_API_KEY、<SCHEME_NAME>_TOKEN、 <SCHEME_NAME>_USERNAME/_PASSWORD 和 <SCHEME_NAME>_CLIENT_ID/_CLIENT_SECRET 的 Wrangler 密钥中读取相同的凭据（参见生成的 .dev.vars.example）。对于 OAuth2，<SCHEME_NAME>_TOKEN 存放你已有的令牌，适用于所有流程；只有在方案声明了客户端凭据流程时，Worker 才会使用客户端 ID 和密钥获取令牌。

---

🧩 生成的工具

• 输入架构是根据你的 OpenAPI 架构映射而来的 JSON Schema 2020-12：保留 integer、format、 pattern、枚举以及 allOf/anyOf/oneOf，将 nullable 转为 null 类型，将 example 转为 examples，并从请求输入中排除 readOnly 属性。

• **验证：**发送任何请求前，都会根据该架构检查参数。问题会以工具错误的形式返回，供模型修正，例如 Invalid arguments for tool 'getPet': /petId: Instance type "string" is invalid. Expected "integer". 参数会按原样传递：不会注入架构默认值。

• **错误：**无效参数、缺少凭据和上游故障都会作为工具错误返回 （isError: true）；未知工具名称则是 JSON-RPC -32602 协议错误，符合 MCP 2026-07-28 规范的要求。

• **标题和注解：**标题取操作的 x-mcp-title，否则取其摘要。提示遵循 HTTP 方法：GET/HEAD/OPTIONS 为只读；POST 非破坏性且非幂等； PUT 和 DELETE 具有破坏性且幂等；PATCH 具有破坏性且非幂等；所有方法均为开放世界。可按操作覆盖各项提示：

  paths:
    /pets/{id}:
      delete:
        x-mcp-title: Remove a pet
        x-mcp-annotations:
          destructiveHint: false # a soft delete
  

• **结构化输出：**如果 JSON 响应是对象，也会作为 structuredContent 返回。 使用 --output-schema 时，每个工具都会将其最低 2xx application/json 响应的架构声明为 outputSchema（仅限对象架构，并移除 writeOnly 属性），且每个响应都会根据该架构进行验证；不匹配的响应会变成工具错误，同时仍显示原始 正文。如果你的规范无法准确描述真实响应，请不要启用此选项。

• **服务说明：**规范的 info.description（去除首尾空白，最多 2000 个字符）会作为服务说明发送给 客户端。

---

🔒 保护 HTTP 服务

生成的 web、streamable-http 和 cloudflare-worker 服务会公开网络端点。 如果它们还持有上游凭据，任何能够访问该端点的人都能使用这些凭据，因此生成器在生成此类服务且未启用保护时会发出警告。

使用 --inbound-auth bearer 要求提供令牌：

openapi-mcp-generator -i openapi.json -o my-mcp -t streamable-http --inbound-auth bearer
openssl rand -hex 32   # put the value in .env as MCP_AUTH_TOKEN (Workers: wrangler secret put MCP_AUTH_TOKEN)

• 每个 MCP 请求都必须发送 Authorization: Bearer <token>；其他请求会在运行任何工具前收到 401。/health 仍然公开。
• 令牌在运行时读取，绝不会写入生成的文件，并会通过恒定时间比较进行校验。 使用 MCP_AUTH_TOKENS=new-token,old-token 可在不停机的情况下轮换令牌。
• 未配置令牌时，服务会以默认拒绝方式返回 503。
• SSE 会话会绑定到建立会话时使用的令牌；使用另一个 令牌重放会话 ID 时，会收到 404。Streamable HTTP 为无状态模式，并会在每个请求中校验令牌。
• 支持自定义请求头的客户端（Claude Code、Cursor、VS Code、MCP Inspector、mcp-remote） 会直接发送令牌。Claude.ai 和 ChatGPT 连接器使用 OAuth 或不进行身份验证；请将它们置于支持 OAuth 的网关后。

使用 --header-passthrough X-API-Key 让每位用户自行提供上游密钥：列出的请求头会按请求转发，因此服务端无需存储共享密钥。转发的请求头会满足凭据通过该请求头传递的安全方案，因此 AND 要求中的其他方案仍会从服务端配置中应用。启用 --inbound-auth bearer 时，透传功能无法转发 Authorization，因为该请求头承载 MCP 令牌。

浏览器来源。 Node HTTP 服务会拒绝 Origin 既不是环回地址、也未列入 MCP_ALLOWED_ORIGINS（逗号分隔）的浏览器请求，从而阻止对运行在你机器上的服务发起 DNS 重绑定攻击。未发送 Origin 请求头的 MCP 客户端不受影响。

--inbound-auth 对 stdio 无效：stdio 服务没有网络端点，只有启动它的进程能够与之通信。

发现漏洞？请参阅 SECURITY.md。

---

🔎 使用 OpenAPI 扩展筛选端点

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

• 扩展：x-mcp: true | false
• 默认值：true（默认包含）
• 优先级：操作 > 路径 > 根（采用第一个非 undefined 值）
• CLI 选项：--default-include false，将默认行为改为默认排除

示例：

# Optional root-level default
x-mcp: true

paths:
  /pets:
    x-mcp: false # exclude all ops under /pets
    get:
      x-mcp: true # include this operation anyway

  /users/{id}:
    get:
      # no x-mcp -> included by default

此功能使用标准 OpenAPI 扩展（x-… 字段）。详情请参阅 OpenAPI 扩展指南。

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

从命令行筛选

无需编辑规范文件即可整理大型 API：

openapi-mcp-generator -i openapi.json -o my-mcp \
  --include-tags pets,store --exclude-operations deletePet

• --include-tags / --exclude-tags 按不区分大小写的方式匹配操作标签。
• --include-operations / --exclude-operations 匹配 operationId 或生成的工具名称。
• 筛选器在 x-mcp 和 --default-include 之后应用，因此不会重新纳入已排除的操作。包含列表会合并（操作匹配任意一项即可保留），排除项始终优先。
• 编程 API 接受相同的筛选器：includeTags、excludeTags、includeOperations、excludeOperations。

---

▶️ 运行生成的服务

cd path/to/output/dir
npm install

# Run in stdio mode
npm start

# Run in web server mode
npm run start:web

# Run in StreamableHTTP mode
npm run start:http

🧪 浏览器交互环境

为 web、streamable-http 和 cloudflare-worker 生成的服务会在 / 提供交互环境（http://localhost:<port>/；对于 Worker，使用 npm run dev 时为 http://localhost:8787/）。该页面会列出工具，根据每个工具的输入架构生成表单、运行工具并显示每条 JSON-RPC 消息，还提供复制为 curl 的功能，以及适用于 Claude Code、Cursor 和 VS Code 的现成配置。如果服务是使用 --inbound-auth bearer 生成的，请粘贴 MCP_AUTH_TOKEN 的值；该值会保留在浏览器标签页中。

• 页面由服务自身的源提供，并采用严格的 Content-Security-Policy，因此本地测试无需更改 CORS 或 MCP_ALLOWED_ORIGINS。服务输出始终以文本形式呈现。
• 页面还提供 Resources、Prompts（含参数补全）、Logs 和 Raw JSON-RPC 标签页；对于耗时较长的工具调用，会显示进度和 Cancel 按钮；并可响应服务请求：elicitation 表单、sampling（由你输入回复）和 roots。
• 同一个开源页面托管在 mcp.pidata.tech/playground，无需安装任何内容即可连接到任意远程 MCP 服务：支持自定义标头、OAuth 登录（发现、Client ID Metadata Documents 或动态注册、PKCE），以及可选的开源中继，适用于会阻止浏览器请求的服务。生成的 Workers 会响应 CORS，因此该页面（以及其他浏览器客户端）可直接访问它们；对于 Node 服务，请将页面的源添加到 MCP_ALLOWED_ORIGINS。
• 设置 MCP_PLAYGROUND=off（Node）或将 MCP_PLAYGROUND 变量设为 "off"（Worker）即可停止提供此页面，例如在生产环境中使用。
• stdio 服务没有 HTTP 端点；请使用 MCP Inspector 测试它们。

---

⚠️ 要求

• 运行生成器需要 Node.js 22.19 或更高版本；生成的项目需要 Node.js 22 或更高版本（Node 20 已于 2026 年 4 月结束生命周期）

---

Star 历史

## 🤝 贡献

欢迎贡献！

1. Fork 此仓库
2. 创建功能分支：git checkout -b feature/amazing-feature
3. 运行 npm run format.write 格式化代码
4. 提交更改：git commit -m "Add amazing feature"
5. 推送并发起 PR

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

---

📄 许可证

MIT 许可证 — 完整详情请参阅 LICENSE。