OpenAPI-MCP：允许AI代理通过现有API文档访问任何API的容器化MCP服务器

[](https://github.com/ckanthony/open api-mcp/actions/workflows/ci.yml)

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

OpenAPI-MCP是一个容器化的MCP服务器，它读取一个swagger.json或openapi.yaml文件，并生成相应的模型上下文协议（MCP）工具集。这使得兼容MCP的客户端如Cursor能够与标准OpenAPI规范描述的API进行交互。现在，您只需提供API的OpenAPI/Swagger规范即可让您的AI代理访问任何API——无需额外编码。

目录

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

演示

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

为什么选择OpenAPI-MCP？

• 标准合规性： 利用现有的OpenAPI/Swagger文档。
• 自动工具生成： 无需手动配置每个端点即可创建MCP工具。
• 灵活的API密钥处理： 安全地管理代理API的API密钥认证，而不将密钥暴露给MCP客户端。
• 本地及远程规范： 支持本地规范文件或远程URL。
• 容器化工具： 使用Docker轻松部署并作为容器化服务运行。

特性

• 支持OpenAPI v2（Swagger）和v3： 解析标准规范格式。
• 模式生成： 根据OpenAPI操作参数和请求/响应定义生成MCP工具模式。
• 安全的API密钥管理：
  • 根据命令行配置将API密钥注入到请求中（header，query，path，cookie）。
    • 直接从标志（--api-key），环境变量（--api-key-env）或位于本地规范旁边的.env文件加载API密钥。
    • 隐藏API密钥，使其不被最终的MCP客户端（例如AI助手）看到。
• 服务器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镜像：

   # 导航到仓库根目录
   cd openapi-mcp
   # 构建Docker镜像（根据需要标记，例如openapi-mcp:latest）
   docker build -t openapi-mcp:latest .
   

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

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

     • 创建一个包含您的openapi.json或swagger.yaml的目录（例如./my-api）。
     • 如果API需要密钥，在同一目录下（例如./my-api/.env）创建一个.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 Run选项：

     • -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容器： 从包含example文件夹的openapi-mcp根目录，运行以下命令：

   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
   # 这会基于../Dockerfile构建镜像
   # 它不会使用公共Docker Hub镜像
   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	(无)
--port	运行MCP服务器的端口。	int	8080
--api-key	直接API密钥值（出于安全性考虑，建议使用--api-key-env或.env文件）。	string	(无)
--api-key-env	包含API密钥的环境变量名称。如果规范是本地的，还会检查规范目录中的.env文件。	string	(无)
--api-key-name	如果使用密钥则必需。 API密钥参数的名称（header，query，path或cookie名称）。	string	(无)
--api-key-loc	如果使用密钥则必需。 API密钥的位置：header，query，path或cookie。	string	(无)
--include-tag	要包含的标签（可以重复）。如果使用包含标志，则仅暴露包含的项。	string slice	(无)
--exclude-tag	要排除的标签（可以重复）。排除在包含之后应用。	string slice	(无)
--include-op	要包含的操作ID（可以重复）。	string slice	(无)
--exclude-op	要排除的操作ID（可以重复）。	string slice	(无)
--base-url	手动覆盖从规范检测到的目标API服务器基础URL。	string	(无)
--name	生成的MCP工具集的默认名称（如果规范没有标题则使用）。	string	"OpenAPI-MCP Tools"
--desc	生成的MCP工具集的默认描述（如果规范没有描述则使用）。	string	"由OpenAPI规范生成的工具"

注意： 您可以通过运行带有--help标志的工具来获取此列表（例如docker run --rm ckanthony/openapi-mcp:latest --help）。

环境变量

• REQUEST_HEADERS：设置此环境变量为JSON字符串（例如'{"X-Custom": "Value"}'）以向所有传出请求添加自定义头。