关键词

API集成AI工具后端服务OpenAPI转工具开发者工具

项目简介

OpenAPI-MCP 是一个 Docker 化的 MCP (Model Context Protocol) 服务器，它可以读取现有的 OpenAPI (v3) 或 Swagger (v2) API 规范文件，并自动将其中定义的 API 操作转换为 AI 助手可理解和调用的 MCP 工具。这使得 AI 代理能够轻松访问任何具有标准 API 文档的外部服务，无需为每个 API 手动编写工具定义代码。

该服务器通过 HTTP/SSE 传输协议与 MCP 客户端通信，接收客户端请求（如获取工具列表、调用工具），执行相应的 API 调用，并将结果以 MCP 格式返回。

主要功能点

  • 自动工具生成： 从 OpenAPI 或 Swagger 规范文件自动创建 MCP 工具定义，无需手动配置每个 API 端点。
  • 广泛的规范支持： 支持 OpenAPI v3 和 Swagger v2 两种主要规范格式。
  • 安全 API 密钥处理： 可以在服务器端配置和注入 API 密钥，无需暴露密钥给 AI 客户端。支持将密钥从环境变量或 '.env' 文件读取，并注入到目标 API 请求的 Header、Query 参数、Path 或 Cookie 中。
  • 灵活的规范加载： 支持加载本地文件路径或远程 URL 的规范文件。
  • Docker 化部署： 提供预构建的 Docker 镜像，方便快速安装和运行。
  • 操作过滤： 支持根据 Tag 或 Operation ID 过滤要暴露给 AI 的 API 操作。
  • 基本能力声明： 实现 MCP 的 'initialize' 和 'tools/list' 方法，向客户端声明支持工具和资源（API 规范作为一种资源）能力。
  • JSON-RPC 通信： 使用 JSON-RPC 2.0 协议进行消息交换，通过 HTTP POST 发送请求，通过 HTTP GET (SSE) 接收响应和通知。

安装步骤

推荐使用 Docker 安装：

  1. 安装 Docker： 确保您的系统已安装 Docker。
  2. 拉取镜像： 打开终端，运行以下命令拉取预构建的 Docker 镜像： 
    docker pull ckanthony/openapi-mcp:latest

您也可以选择从源代码构建 Docker 镜像（不推荐普通用户）：

  1. 克隆仓库：'git clone https://github.com/ckanthony/openapi-mcp.git'
  2. 进入目录：'cd openapi-mcp'
  3. 构建镜像：'docker build -t openapi-mcp:latest .'

服务器配置 (供 MCP 客户端使用)

MCP 客户端需要知道如何启动和连接到这个服务器。以下是典型的 JSON 配置格式示例，以及根据此仓库生成配置时的关键信息说明：

// 这是一个示例配置结构，具体字段可能因 MCP 客户端而异
// 但通常需要服务器启动命令和参数。
{
  "server name": "OpenAPI-MCP Instance", // 为此服务器实例命名
  "command": [
    "docker", // 如果是 Docker 运行，命令通常是 "docker"
    "run",
    "--rm",
    "-p",
    "8080:8080", // 将容器端口 8080 映射到主机端口 8080
    "-v",
    "/path/to/your/spec_dir:/app/spec", // 挂载包含您的 API 规范和 .env 文件的本地目录
    "--env-file",
    "/path/to/your/spec_dir/.env", // 挂载您的 .env 文件（如果需要 API 密钥）
    "ckanthony/openapi-mcp:latest" // 使用的 Docker 镜像名称
  ],
  "args": [
    "--spec", "/app/spec/your_openapi_spec.json", // 容器内规范文件的路径或一个远程 URL
    "--port", "8080", // MCP 服务器在容器内监听的端口 (需与 -p 映射的容器端口一致)
    "--api-key-env", "YOUR_API_KEY_VAR_NAME", // .env 文件中 API 密钥对应的环境变量名
    "--api-key-name", "X-API-Key", // 目标 API 期望的 API 密钥参数名 (如 Header 名称)
    "--api-key-loc", "header", // 目标 API 期望的 API 密钥位置 ("header", "query", "path", "cookie")
    // 以下是可选参数：
    "--base-url", "https://api.example.com/v1", // 强制覆盖规范中的目标 API Base URL
    "--name", "My Custom Toolset Name", // 覆盖 MCP 工具集的默认名称
    "--desc", "Custom description for my tools", // 覆盖 MCP 工具集的默认描述
    "--include-tag", "users", // 只包含带有 "users" 标签的操作 (可重复)
    "--exclude-op", "deleteUserById" // 排除 Operation ID 为 "deleteUserById" 的操作 (可重复)
    // 其他过滤参数...
  ],
  "connection": {
    "type": "http", // 连接类型
    "url": "http://localhost:8080/mcp" // MCP 服务器的 URL (需与 -p 映射的主机端口和 /mcp 路径一致)
    // 客户端会向此 URL 发送 HTTP GET (用于 SSE) 和 HTTP POST 请求
  }
}
  • 'command': AI 客户端用于启动服务器进程的命令。如果使用 Docker，这通常是 'docker run ...' 命令，其中包含了将规范文件和潜在 '.env' 文件挂载到容器内、设置端口映射以及指定使用的 Docker 镜像。请确保 '/path/to/your/spec_dir' 替换为您本地包含规范文件的实际目录路径。
  • 'args': 传递给 Docker 容器内 'openapi-mcp' 程序的命令行参数。
    • '--spec': 必须，指定 OpenAPI/Swagger 规范文件的位置。如果文件在挂载目录 '/app/spec' 内，则路径为 '/app/spec/your_openapi_spec.json'；也可以是公共可访问的 URL。
    • '--port': 指定 MCP 服务器在容器内部监听的端口，通常保持默认 '8080'，并通过 'command' 中的 '-p' 参数映射到主机端口。
    • '--api-key-env', '--api-key-name', '--api-key-loc': 如果目标 API 需要 API 密钥认证，这些参数是必须的，用于告诉 'openapi-mcp' 如何获取密钥值（从哪个环境变量读取）以及如何将其注入到对目标 API 的请求中（参数名、位置）。
    • 其他 'args' 参数用于过滤、覆盖默认名称/描述等，根据您的需求可选配置。
  • 'connection.url': 这是 AI 客户端连接 MCP 服务器的 HTTP/SSE 入口点 URL。通常是 'http://' 或 'https://' 加上主机地址和 'command' 中 '-p' 参数映射的主机端口，以及 '/mcp' 路径。

基本使用方法

  1. 准备 API 规范和密钥： 获取您想要集成到 AI 助手的 API 的 OpenAPI/Swagger 规范文件（JSON 或 YAML 格式），以及该 API 如果需要认证所需的 API 密钥。将规范文件保存在一个本地目录，并在同一目录下创建一个 '.env' 文件，将 API 密钥存储在 '.env' 文件中（例如 'MY_API_KEY=your_actual_key'）。
  2. 运行 Docker 容器： 使用上面“安装步骤”和“服务器配置”中介绍的 'docker run' 命令，根据您的实际文件路径、环境变量名和 API 密钥详情进行调整，启动 'openapi-mcp' 容器。例如： 
    docker run -p 8080:8080 --rm \
  -v $(pwd)/my-api-docs:/app/spec \
  --env-file $(pwd)/my-api-docs/.env \
  ckanthony/openapi-mcp:latest \
  --spec /app/spec/openapi.json \
  --api-key-env MY_API_KEY \
  --api-key-name X-API-Key \
  --api-key-loc header
    这将启动一个 MCP 服务器，监听主机端口 8080，并使用 '/app/spec/openapi.json' 规范文件和 '.env' 中的 'MY_API_KEY' 来配置工具。
  3. 连接 AI 客户端： 配置您的 MCP 兼容 AI 客户端（如 Cursor）连接到 'http://localhost:8080/mcp'。客户端会通过 'initialize' 获取服务器能力，通过 'tools/list' 获取可用的工具列表（即从您的 OpenAPI 规范生成的 API 操作），然后您就可以在 AI 助手中通过这些工具与您的 API 进行交互了。

信息

分类

开发者工具

访问项目