ckanthony/openapi-mcp

OpenAPI-MCP: 让AI代理通过现有API文档访问任何API的Docker化MCP服务器

!openapi-mcp logo

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

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

目录

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

演示

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

!https://github.com/user-attachments/assets/4d457137-5da4-422a-b323-afd4b175bd56

为什么选择OpenAPI-MCP？

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

特性

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

安装

Docker

运行此工具的推荐方式是通过Docker。

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

您可以使用Docker Hub上提供的预构建镜像。

1. 拉取镜像：

   bash
   docker pull ckanthony/openapi-mcp:latest
   

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

本地构建（可选）

1. 本地构建Docker镜像：

   bash
   # 导航到仓库根目录
   cd openapi-mcp
   # 构建Docker镜像（可自定义标签，如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）。

     bash
     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和直接环境变量：

     bash
     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并注册账户（提供免费 tier）。
   • 在Weatherbit账户仪表板中找到API密钥。

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

   bash
   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文件夹的目录）运行以下命令：

   bash
   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密钥：

   dotenv
   # example/weather/.env
   API_KEY=YOUR_ACTUAL_WEATHERBIT_KEY
   

2. 使用Docker Compose运行：导航到example目录并运行：

   bash
   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命令接受以下标志：

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

环境变量

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