Name: OpenAPI-MCP服务器
Author: ckanthony

使用说明

OpenAPI-MCP:码头化MCP服务器，允许您的AI代理使用现有API文档访问任何API

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

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

演示

自己运行演示：运行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键(--api-key)，环境变量(--api-key-env)，或 .env 位于本地规范旁边的文件。
  - 对最终MCP客户端（例如AI助手）隐藏API密钥。
服务器URL检测： 使用规范中的服务器URL作为工具交互的基础（可以覆盖）。
过滤： 包含/排除特定操作或标签的选项(--include-tag, --exclude-tag, --include-op, --exclude-op).
请求头注入： 通过以下方式传递自定义标头（例如，用于其他身份验证、跟踪） REQUEST_HEADERS 环境变量。

安装

码头工人

运行此工具的推荐方式是通过码头工人.

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

或者，您可以使用上提供的预构建映像 Docker Hub.

拉取图像：

docker pull ckanthony/openapi-mcp:latest

运行容器： 跟随 docker run 上面的示例，但替换 openapi-mcp:latest 随着 ckanthony/openapi-mcp:latest.

本地建筑（可选）

在本地构建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 .

运行容器： 运行容器时，您需要提供OpenAPI规范和任何必要的API密钥配置。
- 示例1：使用本地规范文件 .env 文件：
  - 创建一个目录（例如。， ./my-api)包含您的 openapi.json 或 swagger.yaml.
  - 如果API需要密钥，请创建 .env 文件在 同一目录 （例如。， ./my-api/.env)与 API_KEY=your_actual_key （替换 API_KEY 如果你的 --api-key-env 旗帜不同）。
```
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密钥，则为必需。
  - （参见 --help 对于所有命令行选项，请运行 docker run --rm openapi-mcp:latest --help)

运行Weatherbit示例（逐步）

此存储库包括一个使用 Weatherbit API。以下是如何使用公共Docker镜像运行它：

查找OpenAPI规范（可选知识）： 许多公共API的OpenAPI/Swagger规范都可以在网上找到。发现它们的一个很好的资源是 APIs.guru本例中使用的Weatherbit规范(weatherbitio-swagger.json)来源于那里。
获取Weatherbit API密钥：
- 首选 Weatherbit.io 并注册一个帐户（他们提供免费等级）。
- 在Weatherbit帐户仪表板中查找您的API密钥。

克隆此存储库： 您需要此存储库中的示例文件。

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

准备环境文件：
- 导航到示例目录： cd example/weather
- 复制示例环境文件： cp .env.example .env
- 编辑新 .env 归档并替换 YOUR_WEATHERBIT_API_KEY_HERE 使用您从Weatherbit获得的实际API密钥。
运行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加载环境变量（特别是 API_KEY)从你的 .env 文件。
- ckanthony/openapi-mcp:latest：使用公共Docker镜像。
- --spec /app/spec/weatherbitio-swagger.json：指向容器内的规范文件。
- 这 --api-key-* 标志配置工具应如何注入API密钥（从 API_KEY env变量，命名 key，放置在 query 字符串）。
访问MCP服务器： MCP服务器现在应该正在运行，并且可以在以下位置访问 http://localhost:8080 对于兼容的客户端。

使用Docker Compose（示例）：

A. docker-compose.yml 文件提供在 example/ 目录演示使用 本地建造 图像。

准备环境文件： 复制 example/weather/.env.example 到 example/weather/.env 并添加您的实际Weatherbit API密钥：
```
# example/weather/.env
API_KEY=YOUR_ACTUAL_WEATHERBIT_KEY
```
使用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 在启动服务之前，在项目根目录中。
- 撰写将阅读 example/docker-compose.yml，构建映像，挂载 ./weather，阅读 ./weather/.env，并启动 openapi-mcp 具有指定命令行参数的容器。
- MCP服务器将在 http://localhost:8080.
停止服务： 按 Ctrl+C 在运行Compose的终端中，或运行 docker-compose down 从 example 另一个终端中的目录。

命令行选项

这 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键参数的名称（头、查询、路径或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工具”
`--desc`	生成的MCP工具集的默认描述（如果规范没有描述，则使用）。	`string`	“由OpenAPI规范生成的工具”

注：您可以通过使用以下命令运行该工具来获取此列表 --help 标志（例如。， docker run --rm ckanthony/openapi-mcp:latest --help).

环境变量

REQUEST_HEADERS：将此环境变量设置为JSON字符串（例如。， '{"X-Custom": "Value"}')将自定义标头添加到全部向目标API发出请求。

使用说明

OpenAPI-MCP:码头化MCP服务器，允许您的AI代理使用现有API文档访问任何API

目录

演示

为什么选择OpenAPI MCP？

特性

安装

码头工人

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

本地建筑（可选）

运行Weatherbit示例（逐步）

命令行选项

环境变量

相关 MCP

Swagger解析与代码生成工具

Codeforces API访问服务

API转CLI命令行工具

OpenAPI工具服务器

OpenAPI规范服务

OpenAPI规范搜索服务