Openapi To

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 标头中包含您的请求，以便在所有日志中跟踪它。

1. 加载OpenAPI规范 从 MCP_OPENAPI_SPEC （URL以开头 http:// 或 https://，或文件路径）。
2. 收集操作 （方法+路径）。过滤器：如果 MCP_INCLUDE_ENDPOINTS 已设置，只保留那些；否则，请输入任何内容 MCP_EXCLUDE_ENDPOINTS。包含优先于排除。
3. 对于每个操作 创建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.
4. 加载MCP服务器指令：默认情况下使用 info.description 从OpenAPI规范。可选地，从加载自定义指令 MCP_INSTRUCTIONS_FILE 并根据以下内容与OpenAPI描述相结合 MCP_INSTRUCTIONS_MODE （默认/替换/附加/预置）。若文件加载失败，服务器将记录一条警告，并仅继续执行OpenAPI指令。

运输： 流式HTTP终结点： POST/mcp 和 GET/mcp.

环境变量（MCP_前缀）

环境变量从以下位置加载 .env 项目根目录中的文件（使用 dotenv).您还可以直接在shell环境中设置它们。看 .env.example 对于模板。

MCP_OPENAPI_SPEC 必须设置。如果它以 http:// 或 https://，它被视为一个URL；否则，它将被视为文件路径。

向后兼容性: MCP_OPENAPI_SPEC_URL 和 MCP_OPENAPI_SPEC_FILE 仍受支持，但已弃用。 MCP_OPENAPI_SPEC 如果设置，则优先。

使用npm运行（本地）

1. 复制 .env.example 到 .env 并且至少设置OpenAPI规范源和API基础URL：

   cp .env.example .env
   # Edit .env: MCP_OPENAPI_SPEC (URL or file path), MCP_API_BASE_URL

1. 安装、构建和启动：

   npm ci
   npm run build
   npm run start

1. 服务器正在监听 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检查员:

1. 启动MCP服务器（见上文）。
2. 运行MCP检查器： npx @modelcontextprotocol/inspector
3. 在检查器UI中，选择 “可流式传输http” 传输类型（非STDIO）。
4. 输入服务器URL: http://localhost:3100/mcp
5. 点击“连接”。

该服务器包括对基于浏览器的MCP客户端的CORS支持，并维护可流式HTTP传输的会话。

使用Docker运行

Docker Hub上的图片： evilfreelancer/openapi到mcp.使用标签 latest 或版本标签（例如。 v1.0.0).

1. 使用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).

1. 复制 .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在另一个容器中运行）

1. 从项目根：

   docker compose up -d

1. 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否则运行失败。

所需的存储库机密 （设置→ 秘密与变量→ 行动）：

类似项目

• 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服务器。