OpenAPI到MCP
独立代理，可转换任何 OpenAPI/Swagger-将HTTP API描述为 MCP（模型上下文协议） 服务器。它在启动时加载规范，通过包含/排除过滤操作，并为每个API操作注册一个MCP工具。工具调用作为对后端API的HTTP请求执行。
当你已经（或想要）一个带有OpenAPI/Swagger规范的REST API时很有用：相同的规范驱动人工智能客户端的人性化API文档和MCP工具。
运作原理
flowchart LR
subgraph startup["Startup"]
A[OpenAPI spec
URL or file] --> B[Load and filter
include or exclude]
B --> C[N MCP tools
one per operation]
end
subgraph runtime["Runtime"]
D[MCP client] |Streamable HTTP
POST/GET /mcp| E[openapi-to-mcp]
E |HTTP| F[Backend API]
end
C -.->|registered in| E日志记录和关联ID
服务器包括全面的日志记录，并支持请求跟踪的相关ID：
- 关联ID：摘自
X-Correlation-ID标头（不区分大小写）或为每个请求自动生成 - 日志级别:
DEBUG,INFO,WARN,ERROR（可通过以下方式配置MCP_LOG_LEVEL一个是默认值：INFO) - 日志格式:
[correlation_id] LEVEL message带有可选上下文数据 - 请求跟踪：所有日志都包含用于通过系统跟踪请求的相关ID
对于E2E测试，通过 X-Correlation-ID 标头中包含您的请求，以便在所有日志中跟踪它。
- 加载OpenAPI规范 从
MCP_OPENAPI_SPEC（URL以开头http://或https://，或文件路径）。 - 收集操作 （方法+路径）。过滤器：如果
MCP_INCLUDE_ENDPOINTS已设置，只保留那些；否则，请输入任何内容MCP_EXCLUDE_ENDPOINTS。包含优先于排除。 - 对于每个操作 创建MCP工具：name=
MCP_TOOL_PREFIX+路径段（例如。api_+messages=api_messages).路径参数包含在工具名称中（例如。/channels/{username}成为channels_username).如果同一路径段被多个方法使用（例如GET和PUT on/pet/{id})，通过附加方法使工具名称唯一（例如。pet_id_get,pet_id_put).从参数和requestBody（Zod）输入模式，handler=HTTP调用MCP_API_BASE_URL. - 加载MCP服务器指令：默认情况下使用
info.description从OpenAPI规范。可选地，从加载自定义指令MCP_INSTRUCTIONS_FILE并根据以下内容与OpenAPI描述相结合MCP_INSTRUCTIONS_MODE（默认/替换/附加/预置）。若文件加载失败，服务器将记录一条警告，并仅继续执行OpenAPI指令。
运输： 流式HTTP终结点： POST/mcp 和 GET/mcp.
环境变量（MCP_前缀）
环境变量从以下位置加载 .env 项目根目录中的文件（使用 dotenv).您还可以直接在shell环境中设置它们。看 .env.example 对于模板。
| 变量 | 描述 | 默认值 |
|---|---|---|
MCP_API_BASE_URL | API请求的基本URL | http://127.0.0.1:3000 |
MCP_API_BASIC_AUTH | API请求的基本身份验证： username:password。当远程API受HTTP基本身份验证保护时使用。如果这和 MCP_API_BEARER_TOKEN 设置，使用Bearer。 | - |
MCP_API_BEARER_TOKEN | API请求的承载令牌。当远程API期望时使用 Authorization: Bearer .优先于 MCP_API_BASIC_AUTH 当两者都设置时。 | - |
MCP_OPENAPI_SPEC | OpenAPI规范源：URL（以开头 http:// 或 https://)或文件路径（例如。 http://api:3000/openapi.json 或 ./openapi.json).自动检测URL与文件。 | - |
MCP_INCLUDE_ENDPOINTS | 逗号分隔 method:path （例如。 get:/messages,get:/channels).如果设置，只有这些成为工具。 | - |
MCP_EXCLUDE_ENDPOINTS | 逗号分隔 method:path 排除。对于include中的终结点忽略。 | - |
MCP_TOOL_PREFIX | 工具名称的前缀（例如。 api_ -> api_messages, api_channels) | （空） |
MCP_SERVER_NAME | 向MCP客户端报告的服务器名称 | openapi-to-mcp |
MCP_PORT | 流式HTTP服务器的端口 | 3100 |
MCP_HOST | 绑定主机 | 0.0.0.0 |
MCP_LOG_LEVEL | 日志级别： DEBUG, INFO, WARN, ERROR 不区分大小写 INFO | |
MCP_INSTRUCTIONS_FILE | 自定义指令文件的路径（包含MCP服务器指令的文本文件） | - |
MCP_INSTRUCTIONS_MODE | 如何将自定义指令与OpenAPI规范描述相结合： default （仅使用OpenAPI描述，忽略自定义文件）， replace （仅使用自定义文件，忽略OpenAPI）， append （OpenAPI+自定义文件）， prepend （自定义文件+OpenAPI）。不区分大小写 | default |
MCP_CONVERT_HTML_TO_MARKDOWN | 将操作说明中的HTML标签转换为Markdown格式。设置为 false 禁用。 | true |
MCP_OPENAPI_SPEC 必须设置。如果它以 http:// 或 https://，它被视为一个URL；否则，它将被视为文件路径。
向后兼容性: MCP_OPENAPI_SPEC_URL 和 MCP_OPENAPI_SPEC_FILE 仍受支持，但已弃用。 MCP_OPENAPI_SPEC 如果设置，则优先。
使用npm运行（本地）
- 复制
.env.example到.env并且至少设置OpenAPI规范源和API基础URL：
cp .env.example .env
# Edit .env: MCP_OPENAPI_SPEC (URL or file path), MCP_API_BASE_URL- 安装、构建和启动：
npm ci
npm run build
npm run start- 服务器正在监听
http://:（默认值http://0.0.0.0:3100).将MCP客户端连接到 发布/获取http://localhost:3100/mcp（流式HTTP）。
确保后端API可在访问 MCP_API_BASE_URL 并且OpenAPI规范URL（或文件）返回有效的OpenAPI 3.x JSON。
使用MCP检查器
使用以下命令测试服务器 MCP检查员:
- 启动MCP服务器（见上文）。
- 运行MCP检查器：
npx @modelcontextprotocol/inspector - 在检查器UI中，选择 “可流式传输http” 传输类型（非STDIO）。
- 输入服务器URL:
http://localhost:3100/mcp - 点击“连接”。
该服务器包括对基于浏览器的MCP客户端的CORS支持，并维护可流式HTTP传输的会话。
使用Docker运行
Docker Hub上的图片： evilfreelancer/openapi到mcp.使用标签 latest 或版本标签（例如。 v1.0.0).
- 使用env vars获取并运行（例如：来自URL的规范，主机上的API）：
docker run --rm -p 3100:3100 \
-e MCP_OPENAPI_SPEC=http://host.docker.internal:3000/openapi.json \
-e MCP_API_BASE_URL=http://host.docker.internal:3000 \
evilfreelancer/openapi-to-mcp:latest在Linux上，您可能需要 --add-host=host.docker.internal:host-gateway 或者使用主机网络。或者传递文件路径并挂载规范：
docker run --rm -p 3100:3100 \
-v $(pwd)/openapi.json:/app/openapi.json:ro \
-e MCP_OPENAPI_SPEC=/app/openapi.json \
-e MCP_API_BASE_URL=http://host.docker.internal:3000 \
evilfreelancer/openapi-to-mcp:latest要在本地构建映像，请执行以下操作： docker build -t openapi-to-mcp . 和使用 openapi-to-mcp 如上述命令中的图像名称。
使用Docker Compose运行
最低限度 docker-compose.yaml 包含，因此您可以运行MCP服务器，并可选择将其指向现有的API。它使用Docker Hub中的映像(evilfreelancer/openapi到mcp).
- 复制
.env.example到.env并设置：
- MCP_OPENAPI_SPEC (URL like http://api:3000/openapi.jsonor file path like./openapi.json） - MCP_API_BASE_URL （例如。 http://api:3000 如果API在另一个容器中运行）
- 从项目根：
docker compose up -d- MCP服务器将在
http://localhost:3100/mcp（流式HTTP）。
要使用本地OpenAPI文件而不是URL，请设置 MCP_OPENAPI_SPEC 到文件路径并将文件装载到容器中（请参见 docker-compose.yaml 评论（如有）。
测试
npm test测试包括：config（env vars，include/exclude，default）、OpenAPI加载器（URL和文件检测，未设置时出错）、指令加载器（文件加载和组合模式）和OpenAPI-tools（过滤、前缀、成功和错误调用API的处理程序）。HTTP被模拟（axios模拟适配器）。
Dockerfile
该项目包括 Dockerfile （Node 20 Alpine）：安装deps，构建TypeScript，生产修剪，运行 node dist/index.js映像中没有开发依赖关系或测试。预构建图像发布到 .要在本地构建：
docker build -t openapi-to-mcp .CI-Docker Hub上的Docker镜像
GitHub操作工作流(.github/workflows/docker-publish.yml)运行测试，然后构建镜像并将其推送到Docker Hub。
- 触发器：手动（操作→ “Docker构建和推送”→ 运行工作流）或推送任何git标签。
- 版本：在标签推送时，图像标签等于git标签（例如。
v1.0.0)；在手动运行时，您可以设置版本（默认latest). - 仅限Main：当被标记触发时，工作流会检查标记是否指向上的提交
main否则运行失败。
所需的存储库机密 （设置→ 秘密与变量→ 行动）：
| 机密 | 描述 |
|---|---|
DOCKERHUB_USERNAME | Docker Hub用户名（图像将为 DOCKERHUB_USERNAME/openapi-to-mcp) |
DOCKERHUB_TOKEN | Docker Hub访问令牌（推荐）或密码 |
类似项目
- mcp openapi代理 （Python）–MCP服务器，将OpenAPI规范中的REST API作为MCP工具公开。低级模式（每个端点一个工具）或FastMCP模式。身份验证和端点筛选。安装：
uvx mcp-openapi-proxy. - openapi mcp代理 （TypeScript）–将OpenAPI服务转换为MCP服务器的CLI；OpenAPI和MCP客户端之间的中间件。
- openapi mcp生成器 （TypeScript）-从OpenAPI 3.0+（stdio、SSE、Streamable HTTP）生成一个完整的MCP服务器项目，并进行Zod验证和认证。安装：
npm install -g openapi-mcp-generator. - FastMCP+OpenAPI （Python）–FastMCP的OpenAPI集成：身份验证、路由映射、参数处理。
- openapi mcp代码生成器 从OpenAPI到MCP服务器的代码生成器（Apache 2.0）。
- Swagger MCP （Vizioz）–Swagger/OpenAPI的人工智能驱动MCP服务器生成；将规格存储在本地。
- Liblab –云服务：从OpenAPI或Postman集合生成和部署MCP服务器。