OpenAPI MCP Server 使用说明

项目简介

OpenAPI MCP Server 是一个基于 Model Context Protocol (MCP) 的服务器实现，它充当 OpenAPI (v3.1) 规范 API 的代理。通过这个工具，你可以使用 Claude Desktop 等 MCP 客户端以自然语言的方式与任何符合 OpenAPI 规范的 API 进行交互。它将 OpenAPI 端点转换为 Claude 可以理解和调用的工具，使得 LLM 能够自动发现 API 功能、理解参数和类型、代表用户发起 API 调用并处理响应。

主要功能点

OpenAPI API 代理: 将任何符合 OpenAPI v3.1 规范的 API 转换为 MCP 服务器。
Claude 工具集成: 自动将 OpenAPI 端点转换为 Claude Desktop 可以识别和调用的工具。
自然语言交互: 允许用户通过 Claude Desktop 使用自然语言与 OpenAPI API 进行交互。
文件上传支持: 支持 OpenAPI 规范中定义的文件上传功能（multipart/form-data）。
参数和类型自动转换: 自动处理 OpenAPI 参数和类型到 MCP 工具的转换。
错误处理: 能够处理 API 调用中的错误，并将错误信息以结构化的方式返回给客户端。

安装步骤

安装依赖: 在项目根目录下运行以下命令安装项目依赖。
```
pnpm install
```
构建项目: 运行以下命令构建项目。
```
pnpm build
```
链接到全局: 运行以下命令将项目链接到全局 'node_modules'，以便 'npx' 可以找到并执行 'openapi-mcp-server' 命令。
```
npm link
```

服务器配置

为了让 Claude Desktop 能够连接到 OpenAPI MCP Server，你需要在 Claude Desktop 的配置文件 'claude_desktop_config.json' 中添加 MCP 服务器的配置信息。以下是一个配置示例，你需要根据你的 OpenAPI 规范文件路径进行调整：

{
  "mcpServers": {
    "your-api-name": {  //  你为你的API服务器起的名字，例如 "petstore-api", "github-api" 等，Claude Desktop 将使用这个名字来标识和调用你的API工具
      "command": "npx",
      "args": [
        "openapi-mcp-server",
        "/abs/path/to/your-openapi.json"  //  你的 OpenAPI 规范文件的绝对路径，例如 "/Users/yourname/specs/petstore-openapi.json"。请替换为你的实际文件路径或URL。
      ]
    }
  }
}

注意:

'"your-api-name"': 是你为这个 API 服务器自定义的名称，在 Claude Desktop 中用于标识和调用工具。
'"command": "npx"' 和 '"args": [...]': 指定了 Claude Desktop 启动 MCP 服务器的命令。这里使用 'npx openapi-mcp-server' 来运行服务器。
'"args"' 数组中的第一个元素 '/abs/path/to/your-openapi.json': 是 OpenAPI 规范文件的路径。你需要将其替换为你的 本地 OpenAPI 规范文件的绝对路径 或者 OpenAPI 规范文件的URL (以 'http://' 或 'https://' 开头)。

基本使用方法

配置 Claude Desktop: 按照上面的 "服务器配置" 步骤修改 'claude_desktop_config.json' 文件，添加你的 API 服务器配置。
重启 Claude Desktop: 重启 Claude Desktop 使配置生效。
与 API 交互: 在 Claude Desktop 中，你可以开始使用自然语言与你的 API 进行交互了。例如，如果你的 OpenAPI 规范描述的是一个宠物商店 API，你可以问 Claude "列出所有可用的宠物" 或者 "获取 ID 为 123 的宠物信息"。Claude Desktop 会自动将你的自然语言请求转换为对 OpenAPI API 的调用，并通过 OpenAPI MCP Server 进行处理。

示例: 假设你配置了一个名为 "petstore-api" 的服务器，并且你的 OpenAPI 规范中定义了一个 "getPetById" 的操作。你可以在 Claude Desktop 中这样提问：

"Can you fetch the details for pet ID 123 from petstore-api?"
"What's the status of my pet with ID 456 using petstore-api?"

Claude Desktop 将会调用 "petstore-api" 服务器，并执行相应的 API 操作，然后将结果返回给你。

文件上传使用: 如果你的 OpenAPI API 接口支持文件上传（multipart/form-data），你可以在自然语言指令中提供本地文件路径。OpenAPI MCP Server 会自动处理文件读取和上传。例如，如果 API 允许你上传用户头像，你可以这样问 Claude：

"Upload my profile picture from ~/Pictures/profile.jpg using petstore-api"

关键词