OpenAPI MCP Server 使用说明

项目简介

OpenAPI MCP Server 是一个基于 Model Context Protocol (MCP) 构建的服务器，它将 OpenAPI (Swagger) 规范定义的 RESTful API 接口转换为 MCP 协议的工具 (Tools)。这使得大型语言模型 (LLM) 能够通过 MCP 协议，以标准化的方式发现和调用外部的 REST API，从而扩展 LLM 的能力边界。

主要功能点

OpenAPI 接口转换为 MCP 工具 (Tools): 服务器能够读取 OpenAPI 规范文件（支持 URL 或本地文件路径），并将其中的每个 API 接口（Path 和 Method）转化为一个独立的 MCP 工具 (Tool)。
动态工具发现: LLM 客户端可以通过 MCP 协议动态发现由 OpenAPI 规范转换而来的工具列表。
工具调用: LLM 客户端可以根据 OpenAPI 规范中定义的参数，通过 MCP 协议调用这些工具，实际执行 REST API 请求。
支持 OpenAPI V3: 支持 OpenAPI V3 规范。
灵活配置: 支持通过环境变量或命令行参数配置 API 基础 URL、OpenAPI 规范路径、API 请求头等信息。
开发工具: 提供开发模式、代码检查、构建脚本等辅助工具，方便开发者进行二次开发和调试。

安装步骤

该 MCP 服务器无需克隆仓库，可以直接通过 'npx' 命令运行，并配置到支持 MCP 协议的客户端 (例如 Claude Desktop)。

服务器配置

要将 OpenAPI MCP Server 配置到 MCP 客户端，您需要提供服务器的启动命令和相关参数。以下是 Claude Desktop 客户端的配置示例 (JSON 格式):

{
  "mcpServers": {
    "openapi": {  // 服务器名称，可以自定义
      "command": "npx",  // 启动命令，使用 npx 运行 npm 包
      "args": ["-y", "@ivotoby/openapi-mcp-server"], // 启动参数，安装并运行 @ivotoby/openapi-mcp-server npm 包
      "env": { // 环境变量配置
        "API_BASE_URL": "https://api.example.com", //  您的 REST API 的基础 URL，例如：https://petstore.swagger.io/v2
        "OPENAPI_SPEC_PATH": "https://api.example.com/openapi.json", // OpenAPI 规范文件的 URL 或本地路径，例如：https://petstore.swagger.io/v2/swagger.json
        "API_HEADERS": "Authorization:Bearer token123,X-API-Key:your-api-key" // (可选)  API 请求头，用于 API 鉴权，多个 header 以逗号分隔，例如 "Authorization:Bearer token123,X-API-Key:your-api-key"
      }
    }
  }
}

配置参数说明:

'server name': MCP 服务器的名称，例如 "openapi"，可以自定义，用于在客户端中标识该服务器。
'command': 启动服务器的命令，这里使用 'npx' 来运行 npm 包。
'args': 传递给 'command' 的参数，'-y' 表示自动确认安装 npm 包，'@ivotoby/openapi-mcp-server' 是该 MCP 服务器的 npm 包名称。
'env': 环境变量配置，用于配置 OpenAPI MCP Server 的行为。
- 'API_BASE_URL': (必填) 您的目标 REST API 的基础 URL。
- 'OPENAPI_SPEC_PATH': (必填) OpenAPI 规范文件的 URL 或本地文件路径。
- 'API_HEADERS': (可选) API 请求头，如果您的 API 需要身份验证，可以在这里配置请求头信息。

请务必根据您的实际 API 情况，替换 'API_BASE_URL'、'OPENAPI_SPEC_PATH' 和 'API_HEADERS' 的值。

基本使用方法

配置 MCP 客户端: 将上述 JSON 配置添加到您的 MCP 客户端配置文件中 (例如 Claude Desktop 的 'claude_desktop_config.json')。
启动 MCP 客户端: 启动您的 MCP 客户端，客户端会自动连接到 OpenAPI MCP Server。
在 LLM 中使用工具: 在 LLM 对话中，您可以指示 LLM 使用由 OpenAPI MCP Server 提供的工具。LLM 可以通过工具名称或描述来识别工具，并根据 OpenAPI 规范中定义的参数调用工具，执行相应的 REST API 请求。
查看工具列表: 您可以使用 MCP 客户端的功能查看由 OpenAPI MCP Server 暴露的工具列表，以便了解可用的 API 接口。

示例场景:

假设您配置了 Petstore API 的 OpenAPI 规范。在 Claude Desktop 中，您可以指示 Claude 使用 'GET-/store/inventory' 工具来获取宠物商店的库存信息。Claude 会通过 MCP 协议调用 OpenAPI MCP Server, 服务器会执行 'GET https://petstore.swagger.io/v2/store/inventory' 请求，并将 API 响应返回给 Claude。

关键词