OpenAPI-MCP: Dockerized MCP Server to allow your AI agent to access any API with existing api docs

OpenAPI-MCP：Docker 化的 MCP 服务，让 AI Agent 借助现有 API 文档访问任意 API

直接从 Swagger/OpenAPI 规范文件生成 MCP 工具定义。

OpenAPI-MCP 是一个 Docker 化的 MCP 服务，可读取 swagger.json 或 openapi.yaml 文件，并生成相应的 Model Context Protocol (MCP) 工具集。这使 Cursor 等兼容 MCP 的客户端能够与标准 OpenAPI 规范所描述的 API 交互。现在，只需提供 API 的 OpenAPI/Swagger 规范，就能让 AI Agent 访问任意 API，无需额外编码。

目录

• 为什么选择 OpenAPI-MCP？
• 功能
• 安装
  • 使用预构建的 Docker Hub 镜像（推荐）
  • 本地构建（可选）
• 运行 Weatherbit 示例（分步指南）
• 命令行选项
  • 环境变量

演示

亲自运行演示：运行 Weatherbit 示例（分步指南）

为什么选择 OpenAPI-MCP？

• 符合标准： 利用现有的 OpenAPI/Swagger 文档。
• 自动生成工具： 无需为每个端点手动配置，即可创建 MCP 工具。
• 灵活管理 API 密钥： 安全管理代理 API 的 API 密钥身份验证，无需向 MCP 客户端公开密钥。
• 本地和远程规范： 支持本地规范文件或远程 URL。
• Docker 化工具： 可轻松通过 Docker 以容器化服务的形式部署和运行。

功能

• 支持 OpenAPI v2（Swagger）和 v3： 解析标准规范格式。
• 生成架构： 根据 OpenAPI 操作参数以及请求/响应定义创建 MCP 工具架构。
• 安全管理 API 密钥：
  • 根据命令行配置将 API 密钥注入请求（header、query、path、cookie）。
    • 可直接从标志（--api-key）、环境变量（--api-key-env）或与本地规范文件位于同一目录的 .env 文件加载 API 密钥。
    • 对最终 MCP 客户端（例如 AI 助手）隐藏 API 密钥。
• 检测服务 URL： 使用规范文件中的服务 URL 作为工具交互的基础 URL（可覆盖）。
• 筛选： 可选择包含/排除特定操作或标签（--include-tag、--exclude-tag、--include-op、--exclude-op）。
• 注入请求标头： 通过 REQUEST_HEADERS 环境变量传递自定义标头（例如，用于额外的身份验证和跟踪）。

安装

Docker

推荐通过 Docker 运行此工具。

使用 Docker Hub 预构建镜像（推荐）

或者，你可以使用 Docker Hub 上提供的预构建镜像。

1. 拉取镜像：

   docker pull ckanthony/openapi-mcp:latest
   

2. 运行容器： 按照上面的 docker run 示例操作，但将 openapi-mcp:latest 替换为 ckanthony/openapi-mcp:latest。

本地构建（可选）

1. 在本地构建 Docker 镜像：

   # Navigate to the repository root
   cd openapi-mcp
   # Build the Docker image (tag it as you like, e.g., openapi-mcp:latest)
   docker build -t openapi-mcp:latest .
   

2. 运行容器： 运行容器时，需要提供 OpenAPI 规范以及任何必要的 API 密钥配置。

   • 示例 1：使用本地规范文件和 .env 文件：

     • 创建一个目录（例如 ./my-api），其中包含 openapi.json 或 swagger.yaml。
     • 如果 API 需要密钥，请在同一目录中创建 .env 文件（例如 ./my-api/.env），并写入 API_KEY=your_actual_key（如果 --api-key-env 标志不同，请替换 API_KEY）。

     docker run -p 8080:8080 --rm \\
         -v $(pwd)/my-api:/app/spec \\
         --env-file $(pwd)/my-api/.env \\
         openapi-mcp:latest \\
         --spec /app/spec/openapi.json \\
         --api-key-env API_KEY \\
         --api-key-name X-API-Key \\
         --api-key-loc header
     

     （根据需要调整 --spec、--api-key-env、--api-key-name、--api-key-loc 和 -p。）

   • 示例 2：使用远程规范 URL 和直接传入的环境变量：

     docker run -p 8080:8080 --rm \\
         -e SOME_API_KEY="your_actual_key" \\
         openapi-mcp:latest \\
         --spec https://petstore.swagger.io/v2/swagger.json \\
         --api-key-env SOME_API_KEY \\
         --api-key-name api_key \\
         --api-key-loc header
     

   • Docker 运行的关键选项：

     • -p <host_port>:8080：将主机上的端口映射到容器的默认端口 8080。
     • --rm：容器退出时自动将其删除。
     • -v <host_path>:<container_path>：将包含规范的本地目录挂载到容器中。请使用绝对路径或 $(pwd)/...。常用的容器路径：/app/spec。
     • --env-file <path_to_host_env_file>：从本地文件加载环境变量（例如 API 密钥）。路径位于主机上。
     • -e <VAR_NAME>="<value>"：直接传入单个环境变量。
     • openapi-mcp:latest：你在本地构建的镜像名称。
     • --spec ...：**必需。**容器内部的规范文件路径（例如 /app/spec/openapi.json）或公开 URL。
     • --port 8080：（可选）更改服务监听的内部端口（必须与 -p 中的容器端口一致）。
     • --api-key-env、--api-key-name、--api-key-loc：如果目标 API 需要 API 密钥，则必须提供这些选项。
     • （运行 docker run --rm openapi-mcp:latest --help 查看所有命令行选项。）

逐步运行 Weatherbit 示例

此仓库包含一个使用 Weatherbit API 的示例。以下说明如何使用公开的 Docker 镜像运行它：

1. 查找 OpenAPI 规范（可选知识）： 许多公开 API 都可以在线找到 OpenAPI/Swagger 规范。APIs.guru 是查找这些规范的优质资源。本示例使用的 Weatherbit 规范（weatherbitio-swagger.json）即来源于此。

2. 获取 Weatherbit API 密钥：

   • 前往 Weatherbit.io 注册账户（该平台提供免费套餐）。
   • 在 Weatherbit 账户控制面板中查找你的 API 密钥。

3. 克隆此仓库： 你需要此仓库中的示例文件。

   git clone https://github.com/ckanthony/openapi-mcp.git
   cd openapi-mcp
   

4. 准备环境文件：

   • 进入示例目录：cd example/weather
   • 复制示例环境文件：cp .env.example .env
   • 编辑新建的 .env 文件，将 YOUR_WEATHERBIT_API_KEY_HERE 替换为你从 Weatherbit 获取的实际 API 密钥。

5. 运行 Docker 容器： 在 openapi-mcp 根目录（即包含 example 文件夹的目录）中运行以下命令：

   docker run -p 8080:8080 --rm \\
       -v $(pwd)/example/weather:/app/spec \\
       --env-file $(pwd)/example/weather/.env \\
       ckanthony/openapi-mcp:latest \\
       --spec /app/spec/weatherbitio-swagger.json \\
       --api-key-env API_KEY \\
       --api-key-name key \\
       --api-key-loc query
   

   • -v $(pwd)/example/weather:/app/spec：将本地 example/weather 目录（包含规范文件和 .env 文件）挂载到容器内的 /app/spec。
   • --env-file $(pwd)/example/weather/.env：告知 Docker 从你的 .env 文件中加载环境变量（具体为 API_KEY）。
   • ckanthony/openapi-mcp:latest：使用公开的 Docker 镜像。
   • --spec /app/spec/weatherbitio-swagger.json：指定容器内的规范文件。
   • --api-key-* 标志用于配置工具如何注入 API 密钥（从 API_KEY 环境变量读取，名称为 key，并放在 query 字符串中）。

6. 访问 MCP 服务： MCP 服务现在应该已启动，并可通过 http://localhost:8080 供兼容的客户端访问。

使用 Docker Compose（示例）：

example/ 目录中提供了 docker-compose.yml 文件，用于演示如何使用本地构建的镜像运行 Weatherbit API 示例。

1. **准备环境文件：**将 example/weather/.env.example 复制到 example/weather/.env，并填入你的实际 Weatherbit API 密钥：

   # example/weather/.env
   API_KEY=YOUR_ACTUAL_WEATHERBIT_KEY
   

2. **使用 Docker Compose 运行：**进入 example 目录并运行：

   cd example
   # This builds the image locally based on ../Dockerfile
   # It does NOT use the public Docker Hub image
   docker-compose up --build
   

   • --build：在启动服务前，强制 Docker Compose 使用项目根目录中的 Dockerfile 构建镜像。
   • Compose 会读取 example/docker-compose.yml，构建镜像，挂载 ./weather，读取 ./weather/.env，并使用指定的命令行参数启动 openapi-mcp 容器。
   • MCP 服务将在 http://localhost:8080 上可用。

3. **停止服务：**在运行 Compose 的终端中按 Ctrl+C，或在另一个终端中从 example 目录运行 docker-compose down。

命令行选项

openapi-mcp 命令接受以下标志：

标志	描述	类型	默认值
--spec	必填。 OpenAPI 规范文件的路径或 URL。	string	(none)
--port	运行 MCP 服务的端口。	int	8080
--api-key	直接提供 API 密钥值（出于安全考虑，请改用 --api-key-env 或 .env 文件）。	string	(none)
--api-key-env	包含 API 密钥的环境变量名称。如果规范文件位于本地，也会检查规范文件所在目录中的 .env 文件。	string	(none)
--api-key-name	使用密钥时必填。 API 密钥参数的名称（标头、查询、路径或 Cookie 名称）。	string	(none)
--api-key-loc	使用密钥时必填。 API 密钥的位置：header、query、path 或 cookie。	string	(none)
--include-tag	要包含的标签（可重复使用）。如果使用了包含标志，则仅公开包含的项目。	string slice	(none)
--exclude-tag	要排除的标签（可重复使用）。排除操作在包含操作之后应用。	string slice	(none)
--include-op	要包含的操作 ID（可重复使用）。	string slice	(none)
--exclude-op	要排除的操作 ID（可重复使用）。	string slice	(none)
--base-url	手动覆盖从规范文件中检测到的目标 API 服务基础 URL。	string	(none)
--name	生成的 MCP 工具集的默认名称（如果规范文件没有标题，则使用此名称）。	string	"OpenAPI-MCP Tools"
--desc	生成的 MCP 工具集的默认描述（如果规范文件没有描述，则使用此描述）。	string	"Tools generated from OpenAPI spec"

注意： 运行此工具并添加 --help 标志即可获取此列表（例如，docker run --rm ckanthony/openapi-mcp:latest --help）。

环境变量

• REQUEST_HEADERS：将此环境变量设为 JSON 字符串（例如，'{"X-Custom": "Value"}'），即可为发往目标 API 的所有请求添加自定义标头。