mcp-openapi-代理

mcp-openapi-proxy是一个 Python 包，它实现了模型上下文协议 (MCP) 服务器，旨在将 OpenAPI 规范定义的 REST API 动态公开为 MCP 工具。这有助于将 OpenAPI 描述的 API 无缝集成到基于 MCP 的工作流中。

目录

• 概述
• 特征
• 安装
  • MCP 生态系统集成
• 操作模式
  • FastMCP 模式（简单模式）
  • 低级模式（默认）
• 环境变量
• 示例
  • Glama示例
  • Fly.io 示例
  • 渲染示例
  • Slack 示例
  • GetZep 示例
  • Virustotal 示例
  • 概念示例
  • Asana 示例
  • APIs.guru 示例
  • NetBox 示例
  • Box API 示例
  • WolframAlpha API 示例
• 故障排除
• 执照

概述

该软件包提供两种操作模式：

• **低级模式（默认）：**动态注册与 OpenAPI 文档中指定的所有有效 API 端点相对应的工具（例如/chat/completions变为chat_completions() ）。
• **FastMCP 模式（简单模式）：**通过基于静态配置公开一组预定义的工具（例如list_functions()和call_function() ）来提供简化的方法。

特征

• **动态工具生成：**从 OpenAPI 端点定义自动创建 MCP 工具。
• **简单模式选项：**通过 FastMCP 模式提供静态配置替代方案。
• **OpenAPI 规范支持：**兼容 OpenAPI v3，并可能支持 v2。
• **灵活过滤：**允许通过路径或其他标准白名单进行端点过滤。
• **有效负载身份验证：**支持通过 JMESPath 表达式进行自定义身份验证（例如，对于 Slack 等 API，它们需要有效负载中的令牌而不是 HTTP 标头）。
• **标头身份验证：**授权标头中API_KEY默认使用Bearer ，可针对 Fly.io 等需要Api-Key API 进行自定义。
• **MCP 集成：**与 MCP 生态系统无缝集成，以调用 REST API 作为工具。

安装

使用以下命令直接从 PyPI 安装包：

MCP 生态系统集成

要将mcp-openapi-proxy整合到您的 MCP 生态系统，请在mcpServers设置中进行配置。以下是一个通用示例：

请参阅下面的示例部分，了解针对特定 API 定制的实际配置。

操作模式

FastMCP 模式（简单模式）

• **启用方式：**设置环境变量OPENAPI_SIMPLE_MODE=true 。
• **描述：**公开一组从代码中定义的特定 OpenAPI 端点派生的固定工具。
• **配置：**依靠环境变量来指定工具行为。

低级模式（默认）

• **描述：**自动将提供的 OpenAPI 规范中的所有有效 API 端点注册为单独的工具。
• **工具命名：**从规范化的 OpenAPI 路径和方法中获取工具名称。
• **行为：**从 OpenAPI 操作摘要和描述生成工具描述。

环境变量

• OPENAPI_SPEC_URL ：（必需）OpenAPI 规范 JSON 文件的 URL（例如https://example.com/spec.json或file:///path/to/local/spec.json ）。
• OPENAPI_LOGFILE_PATH ：（可选）指定日志文件路径。
• OPENAPI_SIMPLE_MODE ：（可选）设置为true以启用 FastMCP 模式。
• TOOL_WHITELIST ：（可选）要作为工具公开的端点路径的逗号分隔列表。
• TOOL_NAME_PREFIX ：（可选）添加到所有工具名称的前缀。
• API_KEY ：（可选）默认情况下，API 的身份验证令牌作为授权标头中的Bearer <API_KEY>发送。
• API_AUTH_TYPE ：（可选）覆盖默认的Bearer Authorization 标头类型（例如 GetZep 的Api-Key ）。
• STRIP_PARAM ：（可选）JMESPath 表达式用于去除不需要的参数（例如 Slack 的token ）。
• DEBUG ：（可选）设置为“true”、“1”或“yes”时启用详细调试日志记录。
• EXTRA_HEADERS ：（可选）附加到传出 API 请求的“Header: Value”格式的附加 HTTP 标头（每行一个）。
• SERVER_URL_OVERRIDE ：（可选）设置时覆盖 OpenAPI 规范中的基本 URL，对于自定义部署很有用。
• TOOL_NAME_MAX_LENGTH ：（可选）将工具名称截断为最大长度。
• 附加变量： OPENAPI_SPEC_URL_<hash> – 每个测试配置的唯一变体（回退到OPENAPI_SPEC_URL ）。
• IGNORE_SSL_SPEC ：（可选）设置为true以在获取 OpenAPI 规范时禁用 SSL 证书验证。
• IGNORE_SSL_TOOLS ：（可选）设置为true以禁用工具发出的 API 请求的 SSL 证书验证。

示例

为了进行测试，您可以按照示例中所示运行 uvx 命令，然后通过 JSON-RPC 消息与 MCP 服务器交互，列出工具和资源。请参阅下面的“JSON-RPC 测试”部分。

Glama示例

Glama 为 mcp-openapi-proxy 提供了最精简的配置，仅需OPENAPI_SPEC_URL环境变量。这种简洁性使其成为快速测试的理想选择。

1. 验证OpenAPI规范

检索 Glama OpenAPI 规范：

确保响应是有效的 OpenAPI JSON 文档。

2. 为 Glama 配置 mcp-openapi-proxy

将以下配置添加到您的 MCP 生态系统设置：

3.测试

使用以下命令启动服务：

然后参考JSON-RPC 测试部分以获取有关列出资源和工具的说明。

Fly.io 示例

Fly.io 提供了一套简单的 API 来管理机器，使其成为理想的起点。请从Fly.io 文档获取 API 令牌。

1. 验证OpenAPI规范

检索 Fly.io OpenAPI 规范：

确保响应是有效的 OpenAPI JSON 文档。

2. 为 Fly.io 配置 mcp-openapi-proxy

更新您的 MCP 生态系统配置：

• OPENAPI_SPEC_URL ：指向 Fly.io OpenAPI 规范。
• API_KEY ：您的 Fly.io API 令牌（替换<your_flyio_token_here> ）。
• API_AUTH_TYPE ：设置为 Fly.io 基于标头的身份验证的Api-Key （覆盖默认Bearer ）。

3.测试

启动服务后，请参阅JSON-RPC 测试部分，获取有关列出资源和工具的说明。

渲染示例

Render 提供可通过 API 管理的基础设施托管服务。提供的配置文件examples/render-claude_desktop_config.json演示了如何以最少的设置快速搭建您的 MCP 生态系统。

1. 验证OpenAPI规范

检索 Render OpenAPI 规范：

确保响应是有效的 OpenAPI 文档。

2. 配置 mcp-openapi-proxy 进行渲染

将以下配置添加到您的 MCP 生态系统设置：

3.测试

使用您的渲染配置启动代理：

然后参考JSON-RPC 测试部分以获取有关列出资源和工具的说明。

Slack 示例

Slack 的 API 展示了如何使用 JMESPath 剥离不必要的令牌负载。请从Slack API 文档获取机器人令牌。

1. 验证OpenAPI规范

检索 Slack OpenAPI 规范：

确保它是一个有效的 OpenAPI JSON 文档。

2. 为 Slack 配置 mcp-openapi-proxy

更新您的配置：

• OPENAPI_SPEC_URL ：Slack 的 OpenAPI 规范 URL。
• TOOL_WHITELIST ：将工具限制于有用的端点组（例如聊天、对话、用户）。
• API_KEY ：您的 Slack 机器人令牌（例如xoxb-... ，替换<your_slack_bot_token> ）。
• STRIP_PARAM ：从请求有效负载中删除令牌字段。
• TOOL_NAME_PREFIX ：将slack_添加到工具名称前面。

3. 测试

启动服务后，请参阅JSON-RPC 测试部分，获取有关列出资源和工具的说明。

GetZep 示例

GetZep 提供免费的云 API，用于内存管理，并提供了详细的接口。由于 GetZep 尚未提供官方的 OpenAPI 规范，因此该项目包含一个托管在 GitHub 上的生成规范，以方便用户使用。用户也可以为任何 REST API 生成 OpenAPI 规范，并在本地引用（例如file:///path/to/spec.json ）。请从GetZep 的文档中获取 API 密钥。

1. 验证OpenAPI规范

检索项目提供的 GetZep OpenAPI 规范：

确保它是有效的 OpenAPI JSON 文档。或者，您可以生成自己的规范并使用file:// URL 引用本地文件。

2. 为 GetZep 配置 mcp-openapi-proxy

更新您的配置：

• OPENAPI_SPEC_URL ：指向项目提供的 GetZep Swagger 规范（或使用file:///path/to/your/spec.json作为本地文件）。
• TOOL_WHITELIST ：限制为/sessions端点。
• API_KEY ：您的 GetZep API 密钥。
• API_AUTH_TYPE ：使用Api-Key进行基于标头的身份验证。
• TOOL_NAME_PREFIX ：将zep_添加到工具名称前面。

3.测试

启动服务后，请参阅JSON-RPC 测试部分，获取有关列出资源和工具的说明。

Virustotal 示例

此示例演示：

• 使用 YAML OpenAPI 规范文件
• 使用自定义 HTTP 身份验证标头“x-apikey”

1. 验证OpenAPI规范

检索 Virustotal OpenAPI 规范：

确保响应是有效的 OpenAPI YAML 文档。

2. 为 Virustotal 配置 mcp-openapi-proxy

将以下配置添加到您的 MCP 生态系统设置：

关键配置点：

• 默认情况下，代理需要 JSON 规范并发送带有 Bearer 前缀的 API 密钥。
• 要使用 YAML OpenAPI 规范，请包含OPENAPI_SPEC_FORMAT="yaml" 。
• 注意：VirusTotal 需要特殊的身份验证标头；EXTRA_HEADERS 用于将 API 密钥传输为“x-apikey：${VIRUSTOTAL_API_KEY}”。

3. 测试

使用 Virustotal 配置启动代理：

启动服务后，请参阅JSON-RPC 测试部分以获取有关列出资源和工具的说明。

概念示例

Notion 的 API 需要通过 HTTP 标头指定特定版本。本示例使用EXTRA_HEADERS环境变量来包含所需的标头，并重点验证 OpenAPI 规范。

1. 验证OpenAPI规范

检索 Notion OpenAPI 规范：

确保响应是有效的 YAML 文档。

2. 为 Notion 配置 mcp-openapi-proxy

将以下配置添加到您的 MCP 生态系统设置：

3. 测试

使用 Notion 配置启动代理：

启动服务后，请参阅JSON-RPC 测试部分以获取有关列出资源和工具的说明。

Asana 示例

Asana 提供了丰富的端点，用于管理工作区、任务、项目和用户。集成测试演示了GET /workspaces 、 GET /tasks和GET /projects等端点的用法。

1. 验证OpenAPI规范

检索 Asana OpenAPI 规范：

确保响应是有效的 YAML（或 JSON）文档。

2. 为 Asana 配置 mcp-openapi-proxy

将以下配置添加到您的 MCP 生态系统设置：

注意：大多数 Asana API 端点都需要身份验证。请使用有效的令牌在您的环境变量或.env文件中设置ASANA_API_KEY 。

3.测试

使用以下命令启动服务：

然后，您可以使用 MCP 生态系统列出并调用/dcim/devices/和/ipam/ip-addresses/等端点的工具。

APIs.guru 示例

APIs.guru 提供了一个包含数千个公共 API 的 OpenAPI 定义目录。本示例演示如何使用 mcp-openapi-proxy 将 APIs.guru 目录公开为 MCP 工具。

1. 验证OpenAPI规范

检索 APIs.guru OpenAPI 规范：

确保响应是有效的 OpenAPI YAML 文档。

2. 为 APIs.guru 配置 mcp-openapi-proxy

将以下配置添加到您的 MCP 生态系统设置：

3. 测试

使用以下命令启动服务：

然后，您可以使用 MCP 生态系统列出和调用在 APIs.guru 目录中定义的工具，例如listAPIs 、 getMetrics和getProviders 。

NetBox 示例

NetBox 是一款开源的 IP 地址管理 (IPAM) 和数据中心基础设施管理 (DCIM) 工具。本示例演示了如何使用 mcp-openapi-proxy 将 NetBox API 公开为 MCP 工具。

1. 验证OpenAPI规范

检索 NetBox OpenAPI 规范：

确保响应是有效的 OpenAPI YAML 文档。

2. 为 NetBox 配置 mcp-openapi-proxy

将以下配置添加到您的 MCP 生态系统设置：

注意：大多数 NetBox API 端点都需要身份验证。请在您的环境或.env文件中设置NETBOX_API_KEY并使用有效的令牌。

3. 测试

使用以下命令启动服务：

然后，您可以使用 MCP 生态系统列出并调用/dcim/devices/和/ipam/ip-addresses/等端点的工具。

Box API 示例

您可以使用自己的开发者令牌集成 Box Platform API，以便对您的 Box 帐户进行身份验证访问。此示例演示了如何将 Box API 端点公开为 MCP 工具。

示例配置： examples/box-claude_desktop_config.json

• 将您的 Box 开发者令牌设置为.env中的环境变量：
  BOX_API_KEY=your_box_developer_token
• 或者使用一行代码运行代理：
  OPENAPI_SPEC_URL="https://raw.githubusercontent.com/APIs-guru/openapi-directory/refs/heads/main/APIs/box.com/2.0.0/openapi.yaml" API_KEY="$BOX_API_KEY" uvx mcp-openapi-proxy

您现在可以使用 MCP 生态系统列出并调用 Box API 工具。有关集成测试，请参阅tests/integration/test_box_integration.py 。

WolframAlpha API 示例

您可以使用自己的 App ID 集成 WolframAlpha API，以实现身份验证访问。本示例演示如何将 WolframAlpha API 端点公开为 MCP 工具。

示例配置： examples/wolframalpha-claude_desktop_config.json

• 将您的 WolframAlpha App ID 设置为.env中的环境变量：
  WOLFRAM_LLM_APP_ID=your_wolfram_app_id
• 或者使用一行代码运行代理：
  OPENAPI_SPEC_URL="https://raw.githubusercontent.com/APIs-guru/openapi-directory/refs/heads/main/APIs/wolframalpha.com/v0.1/openapi.yaml" API_KEY="$WOLFRAM_LLM_APP_ID" uvx mcp-openapi-proxy

您现在可以使用 MCP 生态系统列出并调用 WolframAlpha API 工具。有关集成测试，请参阅tests/integration/test_wolframalpha_integration.py 。

故障排除

JSON-RPC测试

为了进行其他测试，您可以通过 JSON-RPC 与 MCP 服务器进行交互。启动服务器后，粘贴以下初始化消息：

预期响应：

然后粘贴以下后续消息：

• **缺少 OPENAPI_SPEC_URL：**确保将其设置为有效的 OpenAPI JSON URL 或本地文件路径。
• **规范无效：**验证 OpenAPI 文档是否符合标准。
• **工具过滤问题：**检查TOOL_WHITELIST是否匹配所需的端点。
• **身份验证错误：**确认API_KEY和API_AUTH_TYPE正确。
• **日志记录：**设置DEBUG=true以便将详细内容输出到 stderr。
• **测试服务器：**直接运行：

执照

MIT 许可证