使用说明

项目简介

ivo-toby_mcp-openapi-server 是一个 MCP 服务器，它充当 LLM 和 RESTful API 之间的桥梁。通过读取 OpenAPI (Swagger) 规范，该服务器能够将 API 接口转换为 MCP 协议定义的工具 (Tools)，从而使支持 MCP 协议的 LLM 客户端（如 Claude Desktop）能够发现并调用这些 API。

主要功能点

OpenAPI 转换为 MCP 工具: 自动解析 OpenAPI 规范文件（支持 URL 或本地文件路径），并将 API 接口转换为可在 MCP 中使用的工具。
动态工具注册: 根据 OpenAPI 规范动态注册工具，无需手动配置工具列表。
REST API 调用: 接收来自 LLM 客户端的工具调用请求，根据请求参数调用相应的 REST API，并将 API 响应返回给 LLM。
灵活配置: 支持通过环境变量或命令行参数配置 API 的基础 URL、OpenAPI 规范路径、以及 API 请求头信息。
开发工具支持: 提供构建、开发模式、代码检查和调试等开发辅助工具，方便开发者进行二次开发和扩展。

安装步骤

该 MCP 服务器无需手动克隆仓库和构建，可以直接通过 'npx' 命令运行，并配置到 MCP 客户端中。

服务器配置

要将该 MCP 服务器配置到 MCP 客户端（例如 Claude Desktop），您需要编辑客户端的配置文件，通常是 JSON 格式的配置文件。以下是 Claude Desktop 的配置示例，其他 MCP 客户端的配置方式可能类似。

Claude Desktop 配置示例 (claude_desktop_config.json):

{
  "mcpServers": {
    "openapi": {
      "command": "npx",
      "args": ["-y", "@ivotoby/openapi-mcp-server"],
      "env": {
        "API_BASE_URL": "<您的API基础URL>",  //  您的 REST API 的基础 URL，例如 "https://api.example.com"
        "OPENAPI_SPEC_PATH": "<OpenAPI规范路径>", // OpenAPI 规范文件的 URL 或本地路径，例如 "https://api.example.com/openapi.json"
        "API_HEADERS": "<API请求头信息>" // 可选，API 请求头信息，用于 API 鉴权等，格式为 "Header-Key1:Header-Value1,Header-Key2:Header-Value2"，例如 "Authorization:Bearer token123,X-API-Key:your-api-key"
      }
    }
  }
}

配置参数说明:

'command': MCP 服务器的启动命令，这里使用 'npx' 直接运行 '@ivotoby/openapi-mcp-server' 包。
'args': 传递给启动命令的参数，这里 '-y' 用于 'npx' 自动安装依赖。
'env': 环境变量配置，用于配置 OpenAPI MCP 服务器的具体行为：
- 'API_BASE_URL': 必填。您要桥接的 REST API 的根 URL。
- 'OPENAPI_SPEC_PATH': 必填。OpenAPI 规范文件的 URL (例如 'https://petstore3.swagger.io/api/v3/openapi.json') 或��本地文件路径。
- 'API_HEADERS': 可选。如果您的 API 需要身份验证或其他自定义 Header，可以在这里配置。多个 Header 用逗号分隔，格式为 'Header-Key:Header-Value'。

其他配置方式 (命令行参数):

除了环境变量，您也可以使用命令行参数配置服务器，例如在开发或调试时：

npm run inspect -- \
  --api-base-url https://api.example.com \
  --openapi-spec https://api.example.com/openapi.json \
  --headers "Authorization:Bearer token123,X-API-Key:your-api-key" \
  --name "my-mcp-server" \
  --version "1.0.0"

基本使用方法

配置 MCP 客户端: 根据上述 "服务器配置" 章节，配置您的 MCP 客户端，确保客户端能够连接到该 OpenAPI MCP 服务器。
在 LLM 中使用工具: 配置完成后，当您在支持 MCP 协议的 LLM 应用（如 Claude Desktop）中使用时，LLM 应该能够发现并使用该 MCP 服务器提供的工具。工具的名称和描述信息来源于 OpenAPI 规范中的 'operationId'、'summary' 和 'description' 字段。
调用 API 工具: LLM 在理解用户意图后，可以根据工具的描述和参数信息，生成工具调用请求。MCP 服务器接收到请求后，会调用相应的 REST API，并将结果返回给 LLM。

例如: 如果 OpenAPI 规范中定义了一个 "GET /products/{productId}" 接口，该服务器会将其转换为一个名为 "GET-products-productId" (或根据 'operationId' 或 'summary' 命名) 的 MCP 工具。LLM 可以调用这个工具来获取特定产品的信息。

注意: 该服务器将 OpenAPI 规范中的每个 API 路径和方法都转换为一个独立的 MCP 工具。工具的输入参数根据 OpenAPI 规范中的参数定义生成。

关键词