mcp-openapi-proxy

mcp-openapi-proxy 是一个 Python 包，实现了 Model Context Protocol (MCP) 服务器，旨在将由 OpenAPI 规范定义的 REST API 动态地作为 MCP 工具暴露出来。这有助于将用 OpenAPI 描述的 API 无缝集成到基于 MCP 的工作流中。

目录

• 概述
• 特性
• 安装
  • MCP 生态系统集成
• 操作模式
  • FastMCP 模式（简单模式）
  • 低级模式（默认）
• 环境变量
• 示例
  • Glama 示例
  • Fly.io 示例
  • Render 示例
  • Slack 示例
  • GetZep 示例
  • Virustotal 示例
  • Notion 示例
  • Asana 示例
• 故障排除
• 许可证

概述

该包提供了两种操作模式：

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

特性

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

安装

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

uvx mcp-openapi-proxy

MCP 生态系统集成

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

{
    "mcpServers": {
        "mcp-openapi-proxy": {
            "command": "uvx",
            "args": ["mcp-openapi-proxy"],
            "env": {
                "OPENAPI_SPEC_URL": "${OPENAPI_SPEC_URL}",
                "API_KEY": "${API_OPENAPI_KEY}"
            }
        }
    }
}

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

操作模式

FastMCP 模式（简单模式）

由于原文在此处没有继续给出更多关于 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 的认证令牌，默认情况下在 Authorization 头中发送为 Bearer <API_KEY>。
• API_AUTH_TYPE: （可选）覆盖默认的 Bearer 认证头类型（例如，对于 GetZep 使用 Api-Key）。
• STRIP_PARAM: （可选）JMESPath 表达式，用于移除不需要的参数（例如，对于 Slack 使用 token）。
• DEBUG: （可选）当设置为 "true", "1" 或 "yes" 时，启用详细的调试日志记录。
• EXTRA_HEADERS: （可选）附加到传出 API 请求的额外 HTTP 头，格式为 "Header: Value"（每行一个）。
• 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 规范：

curl https://glama.ai/api/mcp/openapi.json

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

2. 为 Glama 配置 mcp-openapi-proxy

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

{
    "mcpServers": {
        "glama": {
            "command": "uvx",
            "args": ["mcp-openapi-proxy"],
            "env": {
                "OPENAPI_SPEC_URL": "https://glama.ai/api/mcp/openapi.json"
            }
        }
    }
}

3. 测试

启动服务：

OPENAPI_SPEC_URL="https://glama.ai/api/mcp/openapi.json" uvx mcp-openapi-proxy

然后参照JSON-RPC 测试部分的说明来列出资源和工具。

Fly.io 示例

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

1. 验证 OpenAPI 规范

检索 Fly.io 的 OpenAPI 规范：

curl https://raw.githubusercontent.com/abhiaagarwal/peristera/refs/heads/main/fly-machines-gen/fixed_spec.json

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

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

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

{
    "mcpServers": {
        "flyio": {
            "command": "uvx",
            "args": ["mcp-openapi-proxy"],
            "env": {
                "OPENAPI_SPEC_URL": "https://raw.githubusercontent.com/abhiaagarwal/peristera/refs/heads/main/fly-machines-gen/fixed_spec.json",
                "API_KEY": "<your_flyio_token_here>"
            }
        }
    }
}

• 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 示例

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

1. 验证 OpenAPI 规范

检索 Render 的 OpenAPI 规范：

curl https://api-docs.render.com/openapi/6140fb3daeae351056086186

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

2. 为 Render 配置 mcp-openapi-proxy

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

{
    "mcpServers": {
        "render": {
            "command": "uvx",
            "args": ["mcp-openapi-proxy"],
            "env": {
                "OPENAPI_SPEC_URL": "https://api-docs.render.com/openapi/6140fb3daeae351056086186",
                "TOOL_WHITELIST": "/services,/maintenance",
                "API_KEY": "your_render_token_here"
            }
        }
    }
}

3. 测试

使用您的 Render 配置启动代理：

OPENAPI_SPEC_URL="https://api-docs.render.com/openapi/6140fb3daeae351056086186" TOOL_WHITELIST="/services,/maintenance" API_KEY="your_render_token_here" uvx mcp-openapi-proxy

然后参照JSON-RPC 测试部分的说明来列出资源和工具。

Slack 示例

Slack 的 API 展示了如何使用 JMESPath 剔除不必要的令牌负载。从 Slack API 文档 获取一个 bot 令牌。

1. 验证 OpenAPI 规范

检索 Slack 的 OpenAPI 规范：

curl https://raw.githubusercontent.com/slackapi/slack-api-specs/master/web-api/slack_web_openapi_v2.json

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

2. 为 Slack 配置 mcp-openapi-proxy

更新您的配置：

{
    "mcpServers": {
        "slack": {
            "command": "uvx",
            "args": ["mcp-openapi-proxy"],
            "env": {
                "OPENAPI_SPEC_URL": "https://raw.githubusercontent.com/slackapi/slack-api-specs/master/web-api/slack_web_openapi_v2.json",
                "TOOL_WHITELIST": "/chat,/bots,/conversations,/reminders,/files,/users",
                "API_KEY": "<your_slack_bot_token, starts with xoxb>",
                "STRIP_PARAM": "token",
                "TOOL_NAME_PREFIX": "slack_"
            }
        }
    }
}

• OPENAPI_SPEC_URL: Slack 的 OpenAPI 规范文档 URL。
• TOOL_WHITELIST: 将工具限制为有用的端点组（例如 chat, conversations, users）。
• API_KEY: 您的 Slack bot 令牌（例如 xoxb-...，替换 <your_slack_bot_token>）。
• STRIP_PARAM: 从请求负载中移除令牌字段。
• TOOL_NAME_PREFIX: 在工具名称前添加 slack_ 前缀。

3. 测试

在启动服务后，请参考 JSON-RPC 测试 部分中的说明来列出资源和工具。

GetZep 示例

![image](https://github.com/user-attachments/assets/9a4fdabb-fa3d-4626-a50f-438147eadc9f)

GetZep 提供了一个用于内存管理的免费云 API，具有详细的端点。由于 GetZep 没有提供官方的 OpenAPI 规范，因此该项目在 GitHub 上托管了一个生成的规范以方便使用。用户可以类似地为任何 REST API 生成 OpenAPI 规范并本地引用它们（例如 `file:///path/to/spec.json`）。从 [GetZep 的文档](https://link.2) 获取 API 密钥。

#### 1. 验证 OpenAPI 规范

获取项目提供的 GetZep OpenAPI 规范：

#12

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

#### 2. 为 GetZep 配置 mcp-openapi-proxy

更新您的配置：

#13

- **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 测试](#json-rpc-testing) 部分中的说明来列出资源和工具。

### Virustotal 示例

![image](https://github.com/user-attachments/assets/d1760e58-a299-4004-9593-6dbaf3b685a1)

此示例演示了：
- 使用 YAML 格式的 OpenAPI 规范文件
- 使用自定义 HTTP 认证头 "x-apikey"

#### 1. 验证 OpenAPI 规范

检索 Virustotal OpenAPI 规范：

#14

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

#### 2. 为 Virustotal 配置 mcp-openapi-proxy

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

#15

关键配置点：
- 默认情况下，代理期望一个 JSON 规范，并使用 Bearer 前缀发送 API 密钥。
- 要使用 YAML 格式的 OpenAPI 规范，请包含 `OPENAPI_SPEC_FORMAT="yaml"`。
- 注意：VirusTotal 需要一个特殊的认证头；使用 EXTRA_HEADERS 来传递 API 密钥作为 "x-apikey: ${VIRUSTOTAL_API_KEY}"。

#### 3. 测试

使用 Virustotal 配置启动代理：

#16

启动服务后，请参阅 [JSON-RPC 测试](#json-rpc-testing) 部分中的说明来列出资源和工具。

### Notion 示例

![image](https://github.com/user-attachments/assets/45038bcf-9537-4337-8a90-8553ad3aa81b)

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

#### 1. 验证 OpenAPI 规范

检索 Notion OpenAPI 规范：

#17

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

#### 2. 为 Notion 配置 mcp-openapi-proxy

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

#18

#### 3. 测试

使用Notion配置启动代理：

#19

启动服务后，请参阅[JSON-RPC测试](#json-rpc-testing)部分以获取列出资源和工具的说明。

### Asana示例

![image](https://github.com/user-attachments/assets/087571dd-9e06-407e-905c-92815231f618)

Asana提供了丰富的端点来管理工作区、任务、项目和用户。集成测试展示了如何使用如`GET /workspaces`、`GET /tasks`和`GET /projects`等端点。

#### 1. 验证OpenAPI规范

获取Asana的OpenAPI规范：

#20

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

#### 2. 为Asana配置mcp-openapi-proxy

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

#21

在运行集成测试之前，确保已在您的环境中设置了有效的`ASANA_API_KEY`（例如，在您的.env文件中）。然后使用以下命令启动代理：

#22

使用MCP工具（通过JSON-RPC消息或客户端库）与Asana端点进行交互。

## 故障排除

### JSON-RPC测试

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

#23

预期响应：

#24

## 许可证

[MIT许可证](LICENSE)