oas2mcp

oas2mcp 快速入门

你的 REST API 想接入 AI Agent？一个命令，openapi.json 秒变 MCP Server——Rust 编写，零胶水代码。

这是什么？适合谁？

oas2mcp 是一个 Rust 编写的命令行工具，能自动将任何 OpenAPI 规范文件（JSON/YAML）转换为 Model Context Protocol (MCP) Server。它的核心思路极其直接：读入一份 OpenAPI 文档，把文档里的每个 API operation 变成一个 MCP tool——AI Agent 调用这个 tool 时，oas2mcp 自动构建 HTTP 请求发给上游 API，然后把响应返回给 Agent。不需要写一行胶水代码。

与其他 OpenAPI→MCP 转换工具相比，oas2mcp 的差异化在于选用 Rust 而非 TypeScript/Python，带来的优势是：二进制单文件部署、极低内存占用（<10MB）、毫秒级冷启动。劣势也明显：生态更小、Stars 更少（截至 2026-07-06 仅 11 Stars）、需要 Rust 工具链或 Docker 构建。

适合谁？

• 后端开发者：手头有现成的 OpenAPI 文档（Swagger/OpenAPI 3.x），想让 AI Agent 直接调用内部 API，但不想手写 MCP Server
• 平台工程团队：需要为内部微服务体系批量生成 MCP 接入点，oas2mcp 的 JWT 角色权限 + OpenTelemetry 指标正好满足企业级需求
• API 网关运维：配合 Envoy AI Gateway 等代理，oas2mcp 的 stateless streamable-http 模式天然兼容严格代理环境

不适合谁？

• 需要图形化界面的用户——oas2mcp 纯 CLI 操作
• 需要一键 npm/pip install 的用户——需要 Rust 或 Docker 构建
• OpenAPI 文档不规范（缺少 operationId、大量 $ref 嵌套）的场景——自动转换效果会打折扣

准备工作

• 系统要求：Linux/macOS/Windows 均可；Rust 构建需 rustc 1.80+（edition 2024），或 Docker 环境
• 前置条件：一份有效的 OpenAPI 3.x 规范文件（JSON 或 YAML 格式），含明确的 operationId
• 账号要求：无需注册，完全本地运行
• 付费要求：Apache-2.0 开源协议，完全免费，无任何付费 tier
• OpenAPI 文档准备建议：
  • 确保每个 API operation 有明确的 operationId（oas2mcp 优先使用 operationId 作为 MCP tool 名，没有则回退到 <METHOD>_<path> 格式）
  • 建议 path/query/header 参数定义完整，oas2mcp 会自动将它们转为 MCP tool 的顶层参数
  • 如果有私有文档（如内网 Swagger），准备好认证 header

安装

方式一：Cargo 源码构建（推荐）

git clone https://github.com/therealm-tech/oas2mcp.git
cd oas2mcp
cargo build --release
# 二进制文件位于 target/release/oas2mcp

可选：将二进制加入 PATH：

sudo cp target/release/oas2mcp /usr/local/bin/

方式二：Docker 构建

git clone https://github.com/therealm-tech/oas2mcp.git
cd oas2mcp
docker build -t oas2mcp .

之后通过 Docker 运行：

docker run --rm -v $(pwd)/openapi.json:/spec/openapi.json oas2mcp --openapi-file /spec/openapi.json

注意：截至 2026-07-06，oas2mcp 尚未发布到 crates.io 或 Docker Hub，需从源码构建。这是项目尚处于早期阶段的体现。

基础用法

oas2mcp 的核心命令格式：

oas2mcp [OPTIONS]

必须指定 OpenAPI 来源（二选一）：

从本地文件加载（stdio 模式）

最常用的开发场景——直接读取本地的 openapi.json：

oas2mcp --openapi-file ./openapi.json

启动后 oas2mcp 以 stdio 模式运行，等待 MCP 客户端（如 Claude Desktop、Cursor、VS Code Copilot）连接。每个 OpenAPI operation 会自动注册为 MCP tool。

例如，如果 openapi.json 中包含一个 GET /users/{id} 的 operation（operationId: getUser），Agent 就可以直接调用名为 getUser 的 MCP tool，传入 id 参数即可。

从 URL 远程加载

如果你有一个在线托管的 OpenAPI 文档（如公司的 API Gateway 提供的 Swagger UI 端点）：

oas2mcp --openapi-url https://api.example.com/v3/api-docs

对于需要认证的私有文档端点：

oas2mcp --openapi-url https://api.internal.example.com/openapi.json \
  --openapi-header "Authorization: Bearer sk-xxxxxx"

选择传输协议

oas2mcp 支持三种 MCP 传输协议：

streamable-http 模式下，oas2mcp 默认以 stateless 方式运行——每个请求返回单个 application/json 响应体，与 Envoy AI Gateway 等严格代理天然兼容。如需有状态 session，传 --stream-responses 切换到 SSE 流。

进阶功能

周期性热加载

对于频繁更新 API 的团队，oas2mcp 支持自动重新加载 OpenAPI 文档，无需重启服务：

oas2mcp --openapi-url https://api.example.com/openapi.json \
  --reload-every 5m

配合 OAuth2 自动刷新 token，适合长期运行的 MCP 服务：

oas2mcp --openapi-url https://api.example.com/openapi.json \
  --reload-every 5m \
  --openapi-oauth-token-url https://auth.example.com/oauth/token \
  --openapi-oauth-client-id my-client-id \
  --openapi-oauth-client-secret "$OAUTH_SECRET"

认证穿透

oas2mcp 提供了两层认证控制：

1. 静态 Header 附加——所有上游 API 请求统一携带固定 header：

oas2mcp --openapi-file ./openapi.json \
  --header "Authorization: Bearer $(cat /run/secrets/api-token)"

2. 动态 Header 转发（streamable-http 模式）——将 MCP 客户端请求中的 header（如 Authorization）原样转发给上游 API：

oas2mcp --openapi-file ./openapi.json \
  --forward-header Authorization

这意味着 AI Agent 可以用自己的身份凭证访问上游 API，无需共享一个服务级 token。

JWT 角色权限控制（streamable-http 模式）

企业环境中，你可能不希望所有 Agent 都能调用所有 API。oas2mcp 支持基于 JWT 的角色权限：

oas2mcp --openapi-file ./openapi.json \
  --oauth-role-mapper "admin:.*" \
  --oauth-role-mapper "reader:^get|^list|^search"

以上配置：admin 角色可调用所有 tool，reader 角色只能调用以 get/list/search 开头的 tool。

配合 JWT Claim 追踪，可以在日志中看到每次 API 调用的具体用户：

oas2mcp --openapi-file ./openapi.json \
  --trace-claim sub \
  --trace-claim email

可观测性（OpenTelemetry）

oas2mcp 内置 OpenTelemetry 指标导出，统计每个 tool 的调用次数和耗时：

# Prometheus /metrics 端点
oas2mcp --openapi-file ./openapi.json

# OTLP 导出
export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317
oas2mcp --openapi-file ./openapi.json

指标标签包含 tool 名称和调用结果（success/error），自动保持低基数避免指标爆炸。

自定义 CA 证书

如果你的上游 API 使用了企业私有 CA 签发的证书，通过 --ca-cert 信任：

oas2mcp --openapi-file ./openapi.json \
  --ca-cert /etc/ssl/corp-ca.pem

竞品对比

选择建议：追求零依赖单文件部署 + 企业级权限/指标 → oas2mcp；追求开箱即用 + 社区成熟度 → openapi-mcp-generator；需要托管免运维 → Zuplo。

最佳实践

• operationId 规范先行：自动转换的质量高度依赖 OpenAPI 文档的 operationId 命名。建议团队约定 {method}_{resource}_{action} 格式（如 get_user_by_id），Agent 更容易理解和调用
• stdin/stdout 用于本地开发：在 Claude Desktop 的 claude_desktop_config.json 中配置 oas2mcp 的 stdio 模式，无需暴露网络端口
• streamable-http + JWT 用于生产：配合 API Gateway 使用，每个 Agent 使用自己的 JWT 身份，权限从 token claims 中提取
• reload-every 而非重启：API 变更频繁时，用 --reload-every 设置自动重载间隔（如 5m），避免服务中断
• 只导出需要的 operation：如果 OpenAPI 文档包含内部 operation 不希望暴露，用 --oauth-role-mapper 配合正则过滤；或者在文档层做筛选后再传入 oas2mcp
• 关注 upstream 超时：oas2mcp 代理请求到上游 API，上游响应慢会直接影响 Agent 体验。建议配合可观测性指标监控 P99 耗时
• 测试先行：在正式接入 AI Agent 前，用 MCP Inspector 或 curl 手动调用几个 tool 验证转换结果是否符合预期

常见问题 FAQ

Q: oas2mcp 支持 OpenAPI 2.0（Swagger）吗？

目前主要面向 OpenAPI 3.x。Swagger 2.0 文档建议先用 swagger-converter 在线转为 3.0 格式再使用。

Q: 如果 OpenAPI 文档里没有 operationId 怎么办？

oas2mcp 会自动回退到 <HTTP_METHOD>_<path> 格式（例如 GET /users/{id} → get_users_{id}）。但强烈建议在源文档中补充 operationId，生成的方法名更可控。

Q: 支持 WebSocket/Long-polling 等非 REST 模式吗？

不支持。oas2mcp 仅处理标准 HTTP REST API（GET/POST/PUT/PATCH/DELETE），每个 MCP tool 调用对应一次 HTTP 请求-响应。

Q: oas2mcp 的性能如何？适合高并发吗？

Rust 异步运行时（tokio）保证单实例可处理数千并发连接。每个 MCP tool 调用为新 HTTP 请求（无连接池复用），建议配合 HTTP keep-alive 的上游。

Q: 与 Anthropic 官方 MCP Server 推荐列表中的工具有何关系？

截至 2026-07-06，oas2mcp 未出现在 Anthropic 官方 MCP Server 推荐列表中（列表以知名社区项目为主）。oas2mcp 定位为独立开源项目，与官方生态无隶属关系。