mcp-openapi-proxy

mcp-openapi-proxy 是一个 Python 包，它实现了一个模型上下文协议 (MCP) 服务器，旨在动态地将 REST API（由 OpenAPI 规范定义）公开为 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 这样期望令牌在有效负载中而不是 HTTP 标头中的 API）。
• 标头身份验证： 默认情况下，对授权标头中的 API_KEY 使用 Bearer，对于像 Fly.io 这样需要 Api-Key 的 API，可以自定义。
• 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 模式（简单模式）

• 启用方式： 设置环境变量 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 授权标头类型（例如，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：设置为 Api-Key 以用于 Fly.io 基于标头的身份验证（覆盖默认的 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 文档 获取机器人令牌。

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：将工具限制为有用的端点组（例如，聊天、对话、用户）。
• 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 规范：

curl https://raw.githubusercontent.com/matthewhand/mcp-openapi-proxy/refs/heads/main/examples/getzep.swagger.json

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

2. 为 GetZep 配置 mcp-openapi-proxy

更新您的配置：

{
    "mcpServers": {
        "getzep": {
            "command": "uvx",
            "args": ["mcp-openapi-proxy"],
            "env": {
                "OPENAPI_SPEC_URL": "https://raw.githubusercontent.com/matthewhand/mcp-openapi-proxy/refs/heads/main/examples/getzep.swagger.json",
                "TOOL_WHITELIST": "/sessions",
                "API_KEY": "<your_getzep_api_key>",
                "API_AUTH_TYPE": "Api-Key",
                "TOOL_NAME_PREFIX": "zep_"
            }
        }
    }
}

• 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 规范：

curl https://raw.githubusercontent.com/matthewhand/mcp-openapi-proxy/refs/heads/main/examples/virustotal.openapi.yml

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

2. 为 Virustotal 配置 mcp-openapi-proxy

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

{
    "mcpServers": {
        "virustotal": {
            "command": "uvx",
            "args": ["mcp-openapi-proxy"],
            "env": {
                "OPENAPI_SPEC_URL": "https://raw.githubusercontent.com/matthewhand/mcp-openapi-proxy/refs/heads/main/examples/virustotal.openapi.yml",
                "EXTRA_HEADERS": "x-apikey: ${VIRUSTOTAL_API_KEY}",
                "OPENAPI_SPEC_FORMAT": "yaml"
            }
        }
    }
}

关键配置点：

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

3. 测试

使用 Virustotal 配置启动代理：

OPENAPI_SPEC_URL="https://raw.githubusercontent.com/matthewhand/mcp-openapi-proxy/refs/heads/main/examples/virustotal.openapi.yml" API_KEY="your_virustotal_api_key" API_AUTH_HEADER="x-apikey" API_AUTH_TYPE="" OPENAPI_SPEC_FORMAT="yaml" uvx mcp-openapi-proxy

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

Notion 示例

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

1. 验证 OpenAPI 规范

检索 Notion OpenAPI 规范：

curl https://storage.googleapis.com/versori-assets/public-specs/20240214/NotionAPI.yml

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

2. 为 Notion 配置 mcp-openapi-proxy

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

{
  "mcpServers": {
    "notion": {
      "command": "uvx",
      "args": [
        "mcp-openapi-proxy"
      ],
      "env": {
          "API_KEY": "ntn_<your_key>",
          "OPENAPI_SPEC_URL": "https://storage.googleapis.com/versori-assets/public-specs/20240214/NotionAPI.yml",
          "SERVER_URL_OVERRIDE": "https://api.notion.com",
          "EXTRA_HEADERS": "Notion-Version: 2022-06-28"
      }
    }
  }
}

3. 测试

使用 Notion 配置启动代理：

OPENAPI_SPEC_URL="https://storage.googleapis.com/versori-assets/public-specs/20240214/NotionAPI.yml" SERVER_URL_OVERRIDE="https://api.notion.com" EXTRA_HEADERS="Notion-Version: 2022-06-28" API_KEY="ntn_<your_key>" uvx mcp-openapi-proxy

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

Asana 示例

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

1. 验证 OpenAPI 规范

检索 Asana OpenAPI 规范：

curl https://raw.githubusercontent.com/Asana/openapi/refs/heads/master/defs/asana_oas.yaml

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

2. 为 Asana 配置 mcp-openapi-proxy

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

{
  "mcpServers": {
    "asana": {
      "command": "uvx",
      "args": [
        "mcp-openapi-proxy"
      ],
      "env": {
        "OPENAPI_SPEC_URL": "https://raw.githubusercontent.com/Asana/openapi/refs/heads/master/defs/asana_oas.yaml",
        "SERVER_URL_OVERRIDE": "https://app.asana.com/api/1.0",
        "TOOL_WHITELIST": "/workspaces,/tasks,/projects,/users",
        "API_KEY": "${ASANA_API_KEY}"
      }
    }
  }
}

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

ASANA_API_KEY="<your_asana_api_key>" OPENAPI_SPEC_URL="https://raw.githubusercontent.com/Asana/openapi/refs/heads/master/defs/asana_oas.yaml" SERVER_URL_OVERRIDE="https://app.asana.com/api/1.0" TOOL_WHITELIST="/workspaces,/tasks,/projects,/users" uvx mcp-openapi-proxy

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

故障排除

JSON-RPC 测试

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

{"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"claude-ai","version":"0.1.0"}},"jsonrpc":"2.0","id":0}

预期响应：

{"jsonrpc": "2.0", "id": 0, "result": {"capabilities": {...}}}

许可证

MIT 许可证