OpenAPI-MCP：将任何 REST API 变成 AI Agent 工具的桥梁

一款让 AI Agent 无需定制封装即可调用任意 REST API 的代理服务器。

背景：AI Agent 的"接口孤岛"困境

你是否有这样的经历——费尽心思训练了一个 AI Agent，却在关键时刻发现它无法访问你公司内部的订单系统、无法查询天气数据、无法调用第三方支付接口？

这并非 AI 能力不足，而是接口孤岛问题：大量 REST API 遵循 OpenAPI 规范（即 Swagger 规范）设计，有完整的接口文档和参数描述，但 AI Agent 仍然无法直接理解和使用它们，因为传统方式需要为每个 API 编写专门的"适配层"代码。

OpenAPI-MCP 的作者 Roger Gujord 正是发现了这一痛点。他的解决方案优雅而直接：不做定制封装，而是实时将 OpenAPI 规范翻译成 MCP（Model Context Protocol）工具，让 AI Agent 无需任何额外代码即可调用任意遵循 OpenAPI 规范的 REST API。

---

OpenAPI-MCP 工作原理：将 OpenAPI 规范动态转换为 MCP 工具

---

核心技术原理

动态协议转换层

OpenAPI-MCP 本质上是一个协议转换代理服务器。它的工作流程如下：

1. 读取 OpenAPI 规范：通过环境变量 OPENAPI_URL 指定远程或本地 OpenAPI 规范文件（支持 YAML 或 JSON 格式）
2. 解析操作映射：将 OpenAPI 中定义的每个 endpoint（如 GET /weather/{location}）解析为 MCP 工具（tool）
3. 自动生成元数据：从 OpenAPI 文档中提取参数描述、返回值 schema、认证要求，自动生成 MCP 工具的名称、描述和参数 schema
4. 标准化调用转发：接收 MCP 协议格式的调用请求，将其转换为实际的 HTTP 请求，发送给目标 API，并将响应转回 MCP 格式

核心依赖解析

依赖	版本	作用
fastmcp	≥2.13.0	官方 MCP 服务器框架
httpx	≥0.28.1	异步 HTTP 客户端，支持连接池和超时控制
pydantic	≥2.10.6	数据验证和 schema 生成
starlette	≥0.46.1	ASGI 框架底层
uvicorn	≥0.34.0	ASGI 服务器

认证机制

项目实现了双认证体系：

• OAuth2 Client Credentials：自动处理 token 刷新和缓存
• 自定义 Header：支持 X-API-Key 等自定义认证头

两种方式均有自动 token 缓存机制，避免频繁请求认证端点。

传输协议支持

OpenAPI-MCP 支持三种 MCP 传输模式：

传输模式	推荐场景	说明
stdio	CLI 工具、本地集成	标准输入输出，Claude CLI
SSE	Claude Desktop、Cursor、Windsurf	Server-Sent Events，推荐配置
HTTP	远程访问	MCP 官方 HTTP 传输协议

---

使用体验：5 分钟让 Claude 调用真实 API

场景一：零安装体验（uvx）

最轻量的体验方式是使用 uvx 直接运行，无需安装任何依赖：

OPENAPI_URL="https://api.met.no/weatherapi/locationforecast/2.0/swagger" \
SERVER_NAME="weather" \
uvx openapi-mcp

这条命令启动后，Claude Desktop 就能直接调用挪威气象局（api.met.no）的天气 API。问一句"明天奥斯陆天气怎么样"，Claude 会自动调用生成的 weather_get__compact 工具。

场景二：Claude Desktop 集成

1. 复制配置文件到 Claude Desktop 配置目录
2. 通过 npx mcp-remote 将本地服务暴露给 Claude Desktop
3. Claude Desktop 即可在对话中调用任何 OpenAPI 规范的 API

配置示例：

{
  "mcpServers": {
    "weather": {
      "command": "npx",
      "args": ["mcp-remote", "http://127.0.0.1:8001/sse"]
    }
  }
}

Cursor IDE 中调用 MCP 天气工具

场景三：Docker 一键启动

项目提供了 docker-compose 配置，包含 weather 和 petstore 两个示例服务：

./docker-start.sh
# 或
docker-compose up --build -d

自动启动：

• 天气 API 服务（端口 8001）
• Petstore 示例 API 服务（端口 8002）

每个服务都内置了健康检查（/health 端点），Dockerfile 使用 python:3.12-slim 基础镜像，非 root 用户运行，镜像体积控制在合理范围。

---

代码架构分析

目录结构

src/openapi_mcp/
  fastmcp_server.py    # FastMCP 入口，定义服务器和工具注册逻辑
test/                   # 15 个测试文件，覆盖核心功能
examples/               # 演示脚本（FastMCP 简单模式、SSE 模式）

核心设计模式

1. 依赖注入：认证模块、HTTP 客户端均通过参数传入，便于单元测试
2. 指数退避重试：默认最大 3 次重试，对 408/429/5xx 状态码自动重试，Retry-After header 优先
3. 异常层级：完整的 JSON-RPC 错误码体系，符合 MCP 规范
4. 类型安全：全程类型注解，pydantic v2 数据验证

测试覆盖

项目包含 15 个测试文件，覆盖：

• 认证流程（OAuth2、Custom Header）
• Schema 转换
• 重试逻辑
• 多种 MCP 传输模式（stdio、SSE、HTTP）
• 端到端集成测试

文档质量

README 长度超过 25,000 字符，包含详尽的安装指南、配置选项和多种 IDE（Claude Desktop、Cursor、Windsurf）的集成教程。另有 CONTRIBUTING.md、CODE_OF_CONDUCT.md、SECURITY.md 完整配套。

---

局限与注意事项

当前局限

1. 仅支持 REST API：不支持 GraphQL、WebSocket 等其他协议
2. 无 Web UI：所有配置通过环境变量完成，不提供图形界面
3. OpenAPI 规范质量依赖：目标 API 的 OpenAPI 文档质量直接影响工具生成的准确性
4. Python 3.10+ 强制要求：不支持 Python 3.9 及以下版本

安全考量

• Docker 部署使用非 root 用户（appuser）
• 支持 API Key、OAuth2 等认证，但不存储明文密码
• 请求通过 httpx 发送，支持自定义证书配置

---

行业意义

MCP（Model Context Protocol）作为 Anthropic 主导的 AI-Agent 接口标准，正在快速获得生态支持。OpenAPI-MCP 的出现填补了一个关键空白：不是让开发者为 AI 编写适配代码，而是让 AI 自动理解现有的 API 规范。

这种"规范驱动"的思路代表了一种新的集成范式：

• 对于 AI 爱好者：无需写代码即可让 Claude/Cursor 调用真实 API
• 对于开发者：一次编写 OpenAPI 规范，即可在任何 MCP 兼容的 AI 工具中使用

随着 MCP 生态的扩展，OpenAPI-MCP 有望成为 AI Agent 接入现有 API 生态的事实标准工具。