MCP Generator 2 0

MCP发电机3.x

🚀 OpenAPI到FastMCP 3.x服务器生成器

将任何OpenAPI规范转换为具有企业级身份验证、模块化架构和全面中间件支持的生产就绪模型上下文协议（MCP）服务器。

______________________________________________________________________

🎯 概述

MCP Generator 3.x是一个高级代码生成器，可以根据OpenAPI 3.0.x/3.1.x规范自动创建FastMCP 3.x服务器。它通过生成功能齐全的MCP工具来连接REST API和AI代理，Claude、ChatGPT等AI助手可以使用这些工具与您的API进行交互。

支持的OpenAPI版本

• ✅ OpenAPI 3.0.x -完全支持（推荐）
• ✅ OpenAPI 3.1.x -完全支持
• ✅ Swagger 2.0 -完全支持

备注：支持JSON和YAML格式。该生成器包含一个纯Python OpenAPI客户端生成器，不需要Java或Node.js。

🏆 为什么选择MCP Generator 3.x？

竞争比较

MCP Generator 3.x如何与GitHub上的其他OpenAPI到MCP项目进行比较（2026年4月更新）：

|---|---|---|---|---|---|---| | 方法 |代码生成|运行时搜索/代理|运行时代理|代码生成|执行时代理（Docker）|代码生成| | OpenAPI 3.0 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | | OpenAPI 3.1 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | | Swagger 2.0 | ✅ | ❌ | ❌ | ❌ | ✅ | ❌ | | 模块化子服务器 | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | | FastMCP 3.x原生 | ✅ | ❌ | 不适用|❌ | 不适用|❌ | | 可流式传输的HTTP | ✅ | ❌ | ❌ | ✅ | ❌ | ❌ | | JWT/JWKS认证 | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | | OAuth2流 | ✅ | ❌ | 头注入|仅限env变量|❌ | 集管注入| | 中间件堆栈 | ✅ （定时、日志记录、缓存、身份验证）|❌ | ❌ | ❌ | ❌ | ❌ | | MCP资源 | ✅ （GET端点）|❌ | ❌ | ❌ | ❌ | ❌ | | 事件存储 | ✅ （可恢复）|❌ | ❌ | ❌ | ❌ | ❌ | | 自动生成的测试 | ✅ | ❌ | ❌ | ❌ | ❌ | ✅ （eval套房）| | MCP应用程序（UI） | ✅ （表格、图表、表格）|❌ | ❌ | ❌ | ❌ | ❌ | | A2A代理生成 | ✅ （轻量级a2a-sdk）|❌ | ❌ | ❌ | ❌ | ✅ （LangGraph）| | LLM增强文档 | ✅ （OpenAPI叠加1.0）|❌ | ❌ | ❌ | ❌ | ✅ （OpenAPI叠加）| | Docker输出 | ✅ | ❌ | ❌ | ❌ | ✅ 主要的，重要的✅ | | 标签自动发现 | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | | 服务器注册表 | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | | 端点过滤 |基于标签|❌ | 路径过滤器|x-mcp扩展|标签/op过滤器|❌ | | 模式验证 |Pydantic |❌ | ❌ | 佐德|❌ | ❌ | | 积极维护 | ✅ （2026年4月）⚠️ （2026年2月）❌ （2025年4月）✅ （2026年3月）⚠️ （2026年3月）❌ （2025年11月）|

备注: mcpo (4,027★) 解决 逆 问题是将MCP服务器暴露为OpenAPI端点，这是互补的，而不是竞争的。

______________________________________________________________________

✨ FastMCP 3.x功能

MCP Generator 3.x利用了所有最新的FastMCP 3.x功能：

所有功能都可以通过生成的 fastmcp.json:

{
  "features": {
    "search_tools": { "enabled": false },
    "code_mode": { "enabled": false },
    "response_limiting": { "enabled": true, "max_size_bytes": 1048576 },
    "ping_middleware": { "enabled": true },
    "opentelemetry": { "enabled": false, "service_name": "my-api-mcp" }
  }
}

______________________________________________________________________

📦 安装

先决条件

• Python 3.11+：现代字体提示和功能所必需
• OpenAPI规范：API的OpenAPI 3.0.x或3.1.x规范文件（JSON或YAML）

从PyPI安装（推荐）

pip install mcp-generator

# Or with uv
uv pip install mcp-generator

# Verify installation
generate-mcp --help

从源代码安装

git clone https://github.com/quotentiroler/mcp-generator-3.x.git
cd mcp-generator-3.x
uv sync   # or: pip install -e .

# Verify installation
generate-mcp --help

______________________________________________________________________

🚀 快速开始

1.从OpenAPI规范生成MCP服务器

# Using local file (default: ./openapi.json)
generate-mcp

# Using custom file
generate-mcp --file ./my-api-spec.yaml

# Download from URL
generate-mcp --url https://petstore3.swagger.io/api/v3/openapi.json

发生了什么：

• ✅ 根据OpenAPI规范生成Python API客户端
• ✅ 自动查找API路径中未声明的标记（标记自动查找）
• ✅ 创建模块化MCP服务器模块
• ✅ 生成身份验证中间件
• ✅ 创建OAuth2提供程序
• ✅ 写入包文件和测试
• ✅ 输出到 generated_mcp/ 目录

可选功能（默认禁用）

默认情况下，生成器创建一个最小的、生产就绪的服务器。根据需要启用其他功能：

# Enable persistent storage (for OAuth tokens, session state)
generate-mcp --enable-storage

# Enable response caching (reduces backend API calls)
generate-mcp --enable-storage --enable-caching

# Enable MCP resources (expose API data as resources)
generate-mcp --enable-resources

# Enable MCP Apps (interactive UI: tables, charts, forms, detail views)
generate-mcp --enable-apps

# Enable MCP Apps with API-specific display tools from response schemas
generate-mcp --enable-apps --generate-ui

# Enable all features
generate-mcp --enable-storage --enable-caching --enable-resources --enable-apps --generate-ui

# Apply an OpenAPI Overlay to enhance descriptions before generation
generate-mcp --overlay my-overlay.yaml

# Auto-generate an overlay from the spec (no manual file needed)
generate-mcp --auto-overlay

# Generate an A2A agent card and adapter alongside the MCP server
generate-mcp --enable-a2a

可用功能：

备注: --enable-caching 需要 --enable-storage 因为它使用存储后端进行缓存持久化。

为什么默认禁用？

• 使生成的代码保持简单和专注
• 需要管理的依赖关系更少
• 更易于理解和定制
• 没有这些功能，大多数API都能完美工作

生成器将在生成结束时显示哪些功能可用，并使用复制粘贴命令在启用功能的情况下重新生成。

💡 小贴士：运行 generate-mcp --help 查看所有可用选项和示例。

2.注册您的MCP服务器

# Register the generated server
register-mcp ./generated_mcp

# Verify registration
run-mcp --list

这会将您的服务器添加到本地注册表中 ~/.mcp-generator/servers.json 所以你可以很容易地按名称运行它。

3.运行MCP服务器

# Option 1: Run via registry (STDIO mode for local AI clients)
export API_TOKEN="your-api-token-here"  # On Windows: set API_TOKEN=...
run-mcp swagger_petstore_openapi

# Option 2: Run via registry (HTTP mode)
run-mcp swagger_petstore_openapi --mode http --port 8000

# Option 3: Run directly with Python
cd generated_mcp
python swagger_petstore_openapi_mcp_generated.py --transport stdio

# Option 4: Run with FastMCP CLI
cd generated_mcp
# Note: Use :create_server to properly compose the server
fastmcp run swagger_petstore_openapi_mcp_generated.py:create_server
# Or with fastmcp.json config:
fastmcp run fastmcp.json

4.与AI客户端一起使用

克劳德桌面（STDIO模式）

添加 ~/.claude/claude_desktop_config.json:

{
  "mcpServers": {
    "my-api": {
      "command": "python",
      "args": ["/path/to/generated_mcp/swagger_petstore_openapi_mcp_generated.py"],
      "env": {
        "API_TOKEN": "your-api-token-here"
      }
    }
  }
}

______________________________________________________________________

🔍 MCP检验员测试

这 MCP检查员 是MCP服务器的官方调试工具。它为测试生成的服务器提供了可视化UI和CLI模式。

Inspector快速入门

# Generate your MCP server first
generate-mcp --file ./openapi.json

# Test with Inspector using FastMCP (recommended)
cd generated_mcp
fastmcp dev swagger_petstore_openapi_mcp_generated.py:create_server

# Or test directly with Python
npx @modelcontextprotocol/inspector python swagger_petstore_openapi_mcp_generated.py

# Or use environment variables
npx @modelcontextprotocol/inspector -e API_TOKEN=your-token python swagger_petstore_openapi_mcp_generated.py

备注：使用时 fastmcp dev 或 fastmcp run，始终包括 :create_server 正确构建模块化服务器架构。

检查员将：

• 🚀 启动MCP服务器
• 🌐 在以下位置打开浏览器UI http://localhost:6274
• 🔗 通过代理连接 http://localhost:6277
• 🔑 生成安全会话令牌

为您生成的服务器提供检查器功能

🛠️ 工具测试

• 列出从OpenAPI规范生成的所有可用工具
• 基于表单的交互式参数输入
• JSON格式的实时响应可视化
• 测试OAuth2身份验证流

📦 资源勘探

• 分层浏览API资源
• 查看资源元数据和内容
• 测试资源订阅

💬 快速测试

• 交互式提示采样
• 流媒体响应可视化
• 比较多个提示变体

📊 调试

• 请求/响应历史记录
• 可视化错误消息
• 实时服务器通知
• 网络定时信息

CLI自动化模式

非常适合CI/CD和快速开发周期：

# List available tools
npx @modelcontextprotocol/inspector --cli python swagger_petstore_openapi_mcp_generated.py --method tools/list

# Call a specific tool
npx @modelcontextprotocol/inspector --cli python swagger_petstore_openapi_mcp_generated.py \
  --method tools/call \
  --tool-name create_pet \
  --tool-arg 'name=Fluffy' \
  --tool-arg 'status=available'

# Test with environment variables
npx @modelcontextprotocol/inspector --cli \
  -e API_TOKEN=your-token \
  python swagger_petstore_openapi_mcp_generated.py \
  --method tools/list

测试HTTP/SSE传输

如果生成的服务器以HTTP模式运行：

# Start your server in HTTP mode
cd generated_mcp
python swagger_petstore_openapi_mcp_generated.py --transport http --port 8000

# Connect Inspector to running server (SSE transport)
npx @modelcontextprotocol/inspector http://localhost:8000/sse

# Or use Streamable HTTP transport
npx @modelcontextprotocol/inspector http://localhost:8000/mcp --transport http

导出配置

检查器可以导出您的服务器配置，以便在Claude Desktop或其他MCP客户端中使用：

1. 服务器输入按钮 -将单个服务器配置复制到剪贴板
2. 服务器文件按钮 -复制完成 mcp.json 结构

导出配置示例：

{
  "mcpServers": {
    "my-api": {
      "command": "python",
      "args": ["swagger_petstore_openapi_mcp_generated.py"],
      "env": {
        "API_TOKEN": "your-token"
      }
    }
  }
}

开发流程

将Inspector集成到您的开发周期中：

# 1. Generate server from OpenAPI spec
generate-mcp --file ./openapi.yaml

# 2. Test with Inspector UI (interactive development)
cd generated_mcp
npx @modelcontextprotocol/inspector -e API_TOKEN=test python *_mcp_generated.py

# 3. Automated testing (CI/CD)
npx @modelcontextprotocol/inspector --cli \
  -e API_TOKEN=test \
  python *_mcp_generated.py \
  --method tools/list > tools.json

# 4. Test specific tools
npx @modelcontextprotocol/inspector --cli \
  -e API_TOKEN=test \
  python *_mcp_generated.py \
  --method tools/call \
  --tool-name get_user \
  --tool-arg 'user_id=123'

测试生成的服务器的提示

• JWT验证：使用检查器测试JWT身份验证流 --validate-tokens
• OAuth2流量：Inspector支持用于测试OAuth2的承载令牌身份验证
• 范围测试：验证OAuth2配置中的作用域强制
• 错误处理：检查器可视化错误响应和堆栈跟踪
• 演出：使用检查员的计时指标来识别缓慢的操作

有关更多详细信息，请参阅 检查员文件.

______________________________________________________________________

🎨 MCP应用程序--交互式UI显示工具

MCP应用程序为MCP工具响应带来了丰富的交互式UI。您的工具在支持的MCP客户端中呈现为表、图表、表单和详细视图，而不是返回原始JSON。

运作原理

1. --enable-apps 添加了精心策划的API-agnostic显示工具(show_table, show_detail, show_chart, show_form, show_comparison)LLM填充来自任何API响应的数据
2. --generate-ui 此外，还会反思您的OpenAPI响应模式并生成 每个端点显示工具 （例如。， show_pet_table, show_pet_detail)预配置列、徽章和数据类型

# Curated display tools only (works with any API)
generate-mcp --enable-apps

# + API-specific display tools auto-generated from response schemas
generate-mcp --enable-apps --generate-ui

显示工具类型

需求

MCP应用程序需要 prefab-ui （FastMCP Apps渲染库）：

pip install "fastmcp[apps]"

如果 prefab-ui 如果未安装，显示工具将优雅地返回结构化JSON——没有运行时错误。

______________________________________________________________________

🧰 CLI参考

此项目安装三个CLI命令。这是一个快速的备忘单。

生成mcp

• 描述：从OpenAPI 3.0.x/3.1.x规范生成FastMCP 3.x服务器。
• 选项：

- --文件 规范文件的路径（默认：./openapi.json） - --url 从URL下载规范（覆盖--文件）

• 示例：

# Use local file (default)
generate-mcp

# Custom file
generate-mcp --file ./my-api.yaml

# From URL
generate-mcp --url https://petstore3.swagger.io/api/v3/openapi.json

注册mcp

• 说明：管理~/.mcp generator/servers.json上的本地注册表
• 子命令：

- 添加 注册生成的服务器（传递路径时的默认设置） - list显示所有已注册的服务器 - --json输出为json用于脚本/自动化 - 移除 按名称注销服务器 - 出口 将服务器元数据导出为server.json，以便MCP注册表发布 - -o、 --输出 写入文件（默认：stdout）

• 示例：

# Add (explicit)
register-mcp add ./generated_mcp

# Add (implicit)
register-mcp ./generated_mcp

# List registered servers
register-mcp list

# List as JSON
register-mcp list --json

# Remove by name
register-mcp remove swagger_petstore_openapi

# Export server metadata for publishing
register-mcp export swagger_petstore_openapi -o server.json

运行mcp

• 说明：按名称运行已注册的服务器。
• 旗帜：

- --list列出已注册的服务器并退出 - --mode/--传输stdio |http（默认：stdio） - --主机HTTP主机（默认值：0.0.0.0） - --端口HTTP端口（默认值：8000） - --验证令牌启用JWT验证（HTTP模式）

• 示例：

# List servers
run-mcp --list

# Run via STDIO (Linux/macOS)
export API_TOKEN="your-api-token" && run-mcp swagger_petstore_openapi

# Run via STDIO (Windows PowerShell)
powershell
$env:API_TOKEN = "your-api-token"
run-mcp swagger_petstore_openapi

# Run via HTTP
run-mcp swagger_petstore_openapi --mode http --port 8000

# HTTP with JWT validation
run-mcp swagger_petstore_openapi --mode http --port 8000 --validate-tokens

笔记：

• 注册表文件位于~/.mcp生成器/servers.json中
• run-mcp将这些标志转发到生成的服务器入口点。
• 您也可以直接运行生成的脚本：python \_mcp生成的.py

内部注册表（本地）

使用register mcp快速创建您生成的mcp服务器的本地内部注册表。条目位于~/.mcp生成器/servers.json中；在几秒钟内添加/列出/删除，并运行mcp，您可以按名称启动服务器。您可以并行运行多个服务器（例如，不同的HTTP端口），以实现流畅的开发人员工作流程。

发布到自托管的MCP注册表

您可以运行自己的MCP注册表（开源），并将生成的服务器发布到其中：

• 在您的基础设施（Docker Compose/KubeKubernetes）上部署官方注册表服务。配置TLS、数据库（PostgreSQL）和公共基URL。
• 配置身份验证/所有权验证：在注册表中设置GitHub OAuth/OIDC，或使用DNS/HTTP挑战来证明您的命名空间的域所有权。
• 使您的MCP服务器可以通过HTTP访问，并根据注册表模式提供有效的服务器元数据（server.json）。
• 使用发布者CLI指向注册表的基本URL，进行身份验证并发布服务器。验证后，它将通过注册表的API/UI被发现。

注意：此项目（尚未）自动发布。本地每用户注册表（~/.mcp-generator/servers.json）是为了方便开发；发布到中央目录是一个可选的单独步骤。

OAuth2支持

当OpenAPI规范包含OAuth2安全方案时，自动生成OAuth2提供程序。

支持的流量：

• 隐式流
• 授权码流
• 客户端凭据流
• 密码流程

特征：

• 范围提取和验证
• 令牌自省
• 基于JWKS的JWT验证
• 作用域执行中间件

JWT验证

当 --validate-tokens 已启用：

1. 令牌提取：摘录JWT Authorization 头球
2. JWKS发现：自动从OpenAPI规范中发现JWKS端点或使用标准众所周知的路径
3. 签名验证：使用公钥验证JWT签名
4. 索赔验证：检查过期、发行人、受众
5. 范围执行：验证操作所需的范围
6. 身份注入：使工具可以使用用户身份

配置：

JWKS URI、颁发者和受众是 自动提取 在生成过程中，从OpenAPI规范的安全方案中提取。如果OpenAPI规范中没有指定，则使用合理的默认值：

• Jwks类型: {backend_url}/.well-known/jwks.json
• 发行人: {backend_url}
• 观众: backend-api

运行时只需启用JWT验证：

python server_generated.py --transport http --validate-tokens

或在中设置为默认值 fastmcp.json:

{
  "middleware": {
    "config": {
      "authentication": {
        "validate_tokens": true
      }
    }
  }
}

注： 所有JWT配置都被烘焙到生成的代码中——不需要环境变量！

______________________________________________________________________

⚙️ 配置

工具名称自定义

编辑 mcp_generator/config.py:

# Abbreviations for long names
TOOL_NAME_ABBREVIATIONS = {
    'healthcare': 'hc',
    'organization': 'org',
}

# Complete overrides
TOOL_NAME_OVERRIDES = {
    'list_healthcare_users_by_role': 'list_users_by_role',
    'create_smart_app_registration': 'register_smart_app',
}

# Maximum tool name length (MCP/OpenAI limit)
MAX_TOOL_NAME_LENGTH = 64

代码质量

# Format code
uv run ruff format .

# Lint code
uv run ruff check .

# Type checking
uv run mypy mcp_generator/

项目命令

# Generate MCP server from example
generate-mcp --file openapi.yaml

# Validate OpenAPI spec
python mcp_generator/scripts/validate_openapi.py

# Generate JWT keypair for testing
python mcp_generator/scripts/generate_jwt_keypair.py

______________________________________________________________________

📚 示例

示例1：Swagger宠物店

# Generate from Petstore API
generate-mcp --url https://petstore3.swagger.io/api/v3/openapi.json

# Run the server
cd generated_mcp
python swagger_petstore_openapi_mcp_generated.py

示例2:GitHub API

# Download GitHub OpenAPI spec
generate-mcp --url https://raw.githubusercontent.com/github/rest-api-description/main/descriptions/api.github.com/api.github.com.json

# Outputs: 300+ tools for GitHub API operations

______________________________________________________________________

🤝 贡献

欢迎投稿！以下是如何做出贡献：

报告Bug

1. 检查现有问题：https://github.com/quotentiroler/mcp-generator-3.x/issues
2. 使用以下内容创建详细的错误报告：

- OpenAPI规范（经过净化/最小示例） - 完整错误消息和堆栈跟踪 - 重现步骤 - 预期行为与实际行为

推荐功能

1. 打开功能请求问题
2. 描述用例和好处
3. 如果适用，请提供示例

提交拉取请求

1. 分叉存储库
2. 创建要素分支： git checkout -b feature/amazing-feature
3. 进行更改
4. 运行测试： uv run pytest
5. 格式代码： uv run ruff format .
6. 承诺： git commit -m 'Add amazing feature'
7. 推： git push origin feature/amazing-feature
8. 打开拉取请求

开发指南

• 遵循现有代码样式（Ruff格式）
• 为新功能添加测试
• 根据需要更新文档
• 保持提交的重点和描述性

______________________________________________________________________

📄 许可证

该项目根据 Apache许可证2.0.

这意味着：

✅ 你可以：

• 将本软件用于任何目的（商业或非商业）
• 修改源代码
• 分发软件
• 将其包含在专有软件中
• 在SaaS应用程序中使用它
• 授予专利保护

⚠️ 您必须：

• 包括原始许可和版权声明
• 说明对代码所做的重大更改
• 在您的发行版中包含Apache 2.0许可证的副本

❌ 您不能：

• 未经许可使用项目商标
• 追究作者的责任

为什么选择Apache 2.0？

Apache 2.0是一个宽松的许可证，在提供专利保护的同时促进了广泛的采用。它对业务友好，被企业广泛接受，通常用于开发工具和代码生成器。此许可证允许您在项目中使用MCP Generator 3.x，而无需担心copyleft要求。

生成代码： 此工具生成的代码不被视为生成器本身的衍生作品。您可以选择授权您生成的MCP服务器。

有关完整的许可证文本，请参阅 许可证 或访问https://www.apache.org/licenses/LICENSE-2.0

______________________________________________________________________

🙏 致谢

• FastMCP：建立在卓越之上 FastMCP 3.x 框架
• OpenAPI 生成器：用途 OpenAPI 生成器 用于客户端生成
• 模型上下文协议：实现 MCP规范
• 人类：用于MCP标准和Claude Desktop集成

______________________________________________________________________

如果你觉得这个项目有用，请考虑给它一颗星！ ⭐

它帮助其他人发现工具并激励持续发展。

由...制作❤️