mcp-openapi-代理
mcp-openapi-proxy是一个 Python 包,它实现了模型上下文协议 (MCP) 服务器,旨在将 OpenAPI 规范定义的 REST API 动态公开为 MCP 工具。这有助于将 OpenAPI 描述的 API 无缝集成到基于 MCP 的工作流中。
目录
Related MCP server: MCP-OpenAPI
概述
该软件包提供两种操作模式:
**低级模式(默认):**动态注册与 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-KeyAPI 进行自定义。**MCP 集成:**与 MCP 生态系统无缝集成,以调用 REST API 作为工具。
安装
使用以下命令直接从 PyPI 安装包:
uvx mcp-openapi-proxyMCP 生态系统集成
要将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:(可选)覆盖默认的BearerAuthorization 标头类型(例如 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 规范:
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 提供可通过 API 管理的基础设施托管服务。提供的配置文件examples/render-claude_desktop_config.json演示了如何以最少的设置快速搭建您的 MCP 生态系统。
1. 验证OpenAPI规范
检索 Render OpenAPI 规范:
curl https://api-docs.render.com/openapi/6140fb3daeae351056086186确保响应是有效的 OpenAPI 文档。
2. 配置 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. 测试
使用您的渲染配置启动代理:
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 的 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 端点都需要身份验证。请使用有效的令牌在您的环境变量或
3.测试
使用以下命令启动服务:
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 生态系统列出并调用/dcim/devices/和/ipam/ip-addresses/等端点的工具。
APIs.guru 示例
APIs.guru 提供了一个包含数千个公共 API 的 OpenAPI 定义目录。本示例演示如何使用 mcp-openapi-proxy 将 APIs.guru 目录公开为 MCP 工具。
1. 验证OpenAPI规范
检索 APIs.guru OpenAPI 规范:
curl https://raw.githubusercontent.com/APIs-guru/openapi-directory/refs/heads/main/APIs/apis.guru/2.2.0/openapi.yaml确保响应是有效的 OpenAPI YAML 文档。
2. 为 APIs.guru 配置 mcp-openapi-proxy
将以下配置添加到您的 MCP 生态系统设置:
{
"mcpServers": {
"apisguru": {
"command": "uvx",
"args": ["mcp-openapi-proxy"],
"env": {
"OPENAPI_SPEC_URL": "https://raw.githubusercontent.com/APIs-guru/openapi-directory/refs/heads/main/APIs/apis.guru/2.2.0/openapi.yaml"
}
}
}
}3.测试
使用以下命令启动服务:
OPENAPI_SPEC_URL="https://raw.githubusercontent.com/APIs-guru/openapi-directory/refs/heads/main/APIs/apis.guru/2.2.0/openapi.yaml" uvx mcp-openapi-proxy然后,您可以使用 MCP 生态系统列出和调用在 APIs.guru 目录中定义的工具,例如listAPIs 、 getMetrics和getProviders 。
NetBox 示例
NetBox 是一款开源的 IP 地址管理 (IPAM) 和数据中心基础设施管理 (DCIM) 工具。本示例演示了如何使用 mcp-openapi-proxy 将 NetBox API 公开为 MCP 工具。
1. 验证OpenAPI规范
检索 NetBox OpenAPI 规范:
curl https://raw.githubusercontent.com/APIs-guru/openapi-directory/refs/heads/main/APIs/netbox.dev/3.4/openapi.yaml确保响应是有效的 OpenAPI YAML 文档。
2. 为 NetBox 配置 mcp-openapi-proxy
将以下配置添加到您的 MCP 生态系统设置:
{
"mcpServers": {
"netbox": {
"command": "uvx",
"args": ["mcp-openapi-proxy"],
"env": {
"OPENAPI_SPEC_URL": "https://raw.githubusercontent.com/APIs-guru/openapi-directory/refs/heads/main/APIs/netbox.dev/3.4/openapi.yaml",
"API_KEY": "${NETBOX_API_KEY}"
}
}
}
}注意:大多数 NetBox API 端点都需要身份验证。请在您的环境或
3.测试
使用以下命令启动服务:
OPENAPI_SPEC_URL="https://raw.githubusercontent.com/APIs-guru/openapi-directory/refs/heads/main/APIs/netbox.dev/3.4/openapi.yaml" API_KEY="$NETBOX_API_KEY" uvx mcp-openapi-proxy然后,您可以使用 MCP 生态系统列出并调用/dcim/devices/和/ipam/ip-addresses/等端点的工具。
Box API 示例
您可以使用自己的开发者令牌集成 Box Platform API,以便对您的 Box 帐户进行身份验证访问。此示例演示了如何将 Box API 端点公开为 MCP 工具。
示例配置: examples/box-claude_desktop_config.json
"env": {
"OPENAPI_SPEC_URL": "https://raw.githubusercontent.com/APIs-guru/openapi-directory/refs/heads/main/APIs/box.com/2.0.0/openapi.yaml",
"TOOL_WHITELIST": "/folders/{folder_id}/items,/files/{file_id},/search,/recent_items",
"API_KEY": "${BOX_API_KEY}"
}将您的 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 。
注意:免费套餐用户的开发人员 API 密钥限制为 60 分钟 :(。
WolframAlpha API 示例
您可以使用自己的 App ID 集成 WolframAlpha API,以实现身份验证访问。本示例演示如何将 WolframAlpha API 端点公开为 MCP 工具。
示例配置: examples/wolframalpha-claude_desktop_config.json
{
"mcpServers": {
"wolframalpha": {
"command": "uvx",
"args": [
"mcp-openapi-proxy"
],
"env": {
"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}"
}
}
}
}将您的 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 服务器交互。启动服务器后,粘贴以下初始化消息:
{"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":{"protocolVersion":"2024-11-05","capabilities":{"experimental":{},"prompts":{"listChanged":false},"resources":{"subscribe":false,"listChanged":false},"tools":{"listChanged":false}},"serverInfo":{"name":"sqlite","version":"0.1.0"}}}然后粘贴以下后续消息:
{"method":"notifications/initialized","jsonrpc":"2.0"}
{"method":"resources/list","params":{},"jsonrpc":"2.0","id":1}
{"method":"tools/list","params":{},"jsonrpc":"2.0","id":2}**缺少 OPENAPI_SPEC_URL:**确保将其设置为有效的 OpenAPI JSON URL 或本地文件路径。
**规范无效:**验证 OpenAPI 文档是否符合标准。
**工具过滤问题:**检查
TOOL_WHITELIST是否匹配所需的端点。**身份验证错误:**确认
API_KEY和API_AUTH_TYPE正确。**日志记录:**设置
DEBUG=true以便将详细内容输出到 stderr。**测试服务器:**直接运行:
uvx mcp-openapi-proxy