OpenAPI MCP 服务器

一个模型上下文协议 (MCP) 服务器，它将 OpenAPI 端点公开为 MCP 资源。此服务器允许大型语言模型通过 MCP 协议发现并交互 OpenAPI 规范定义的 REST API。

概述

该 MCP 服务器支持两种传输方式：

Stdio Transport （默认）：用于与通过标准输入/输出管理 MCP 连接的 Claude Desktop 等 AI 系统直接集成。
可流式 HTTP 传输：通过 HTTP 连接到服务器，允许 Web 客户端和其他支持 HTTP 的系统使用 MCP 协议。

Related MCP server: File Context MCP

用户快速入门

选项 1：与 Claude Desktop (Stdio Transport) 一起使用

无需克隆此存储库。只需配置 Claude Desktop 即可使用此 MCP 服务器：

找到或创建您的 Claude Desktop 配置文件：
- 在 macOS 上： ~/Library/Application Support/Claude/claude_desktop_config.json
添加以下配置：

{ "mcpServers": { "openapi": { "command": "npx", "args": ["-y", "@ivotoby/openapi-mcp-server"], "env": { "API_BASE_URL": "https://api.example.com", "OPENAPI_SPEC_PATH": "https://api.example.com/openapi.json", "API_HEADERS": "Authorization:Bearer token123,X-API-Key:your-api-key" } } } }

将环境变量替换为您的实际 API 配置：
- API_BASE_URL ：API 的基本 URL
- OPENAPI_SPEC_PATH ：OpenAPI 规范的 URL 或路径
- API_HEADERS ：API 身份验证标头的逗号分隔键值对

选项 2：使用 HTTP 客户端（HTTP 传输）

要将服务器与 HTTP 客户端一起使用：

无需安装！使用 npx 直接运行包：

使用 HTTP 请求与服务器交互：

# Initialize a session (first request) curl -X POST http://localhost:3000/mcp \ -H "Content-Type: application/json" \ -d '{"jsonrpc":"2.0","id":0,"method":"initialize","params":{"client":{"name":"curl-client","version":"1.0.0"},"protocol":{"name":"mcp","version":"2025-03-26"}}}' # The response includes a Mcp-Session-Id header that you must use for subsequent requests # and the InitializeResult directly in the POST response body. # Send a request to list tools # This also receives its response directly on this POST request. curl -X POST http://localhost:3000/mcp \ -H "Content-Type: application/json" \ -H "Mcp-Session-Id: your-session-id" \ -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' # Open a streaming connection for other server responses (e.g., tool execution results) # This uses Server-Sent Events (SSE). curl -N http://localhost:3000/mcp -H "Mcp-Session-Id: your-session-id" # Example: Execute a tool (response will arrive on the GET stream) # curl -X POST http://localhost:3000/mcp \ # -H "Content-Type: application/json" \ # -H "Mcp-Session-Id: your-session-id" \ # -d '{"jsonrpc":"2.0","id":2,"method":"tools/execute","params":{"name":"yourToolName", "arguments": {}}}' # Terminate the session when done curl -X DELETE http://localhost:3000/mcp -H "Mcp-Session-Id: your-session-id"

运输类型

Stdio 传输（默认）

stdio 传输旨在与 Claude Desktop 等通过标准输入/输出管理 MCP 连接的 AI 系统直接集成。这是最简单的设置，无需网络配置。

何时使用：与 Claude Desktop 或其他支持基于 stdio 的 MCP 通信的系统集成时。

可流式传输的 HTTP 传输

HTTP 传输允许通过 HTTP 访问 MCP 服务器，从而使 Web 应用程序和其他支持 HTTP 的客户端能够与 MCP 协议交互。它支持会话管理、流式响应和标准 HTTP 方法。

主要特点：

使用 Mcp-Session-Id 标头进行会话管理
initialize和tools/list请求的 HTTP 响应在 POST 上同步发送。
其他服务器到客户端消息（例如， tools/execute结果、通知）使用服务器发送事件（SSE）通过 GET 连接传输。
支持 POST/GET/DELETE 方法

何时使用：当您需要将 MCP 服务器公开给通过 HTTP 而不是 stdio 进行通信的 Web 客户端或系统时。

配置选项

可以通过环境变量或命令行参数配置服务器：

环境变量

API_BASE_URL - API 端点的基本 URL
OPENAPI_SPEC_PATH - OpenAPI 规范的路径或 URL
API_HEADERS - API 标头的逗号分隔键值对
SERVER_NAME - MCP 服务器的名称（默认值：“mcp-openapi-server”）
SERVER_VERSION - 服务器版本（默认值：“1.0.0”）
TRANSPORT_TYPE - 要使用的传输类型：“stdio”或“http”（默认值：“stdio”）
HTTP_PORT - HTTP 传输端口（默认值：3000）
HTTP_HOST - HTTP 传输的主机（默认值：“127.0.0.1”）
ENDPOINT_PATH - HTTP 传输的端点路径（默认值：“/mcp”）

命令行参数

npx @ivotoby/openapi-mcp-server \ --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" \ --transport http \ --port 3000 \ --host 127.0.0.1 \ --path /mcp

安全注意事项

HTTP 传输验证 Origin 标头以防止 DNS 重新绑定攻击
默认情况下，HTTP 传输仅绑定到本地主机（127.0.0.1）
如果暴露给其他主机，请考虑实施额外的身份验证

调试

查看调试日志：

当使用 Claude Desktop 的 stdio 传输时：
- 日志出现在 Claude Desktop 日志中
使用 HTTP 传输时：
npx @ivotoby/openapi-mcp-server --transport http 2>debug.log

对于开发人员

开发工具

npm run build - 构建 TypeScript 源
npm run clean - 删除构建工件
npm run typecheck - 运行 TypeScript 类型检查
npm run lint - 运行 ESLint
npm run dev - 监视源文件并在发生更改时重建
npm run inspect-watch - 运行检查器并在发生更改时自动重新加载

开发工作流程

克隆存储库
安装依赖项： npm install
启动开发环境： npm run inspect-watch
对src/中的 TypeScript 文件进行更改
服务器将自动重建并重启

贡献

分叉存储库
创建功能分支
进行更改
运行测试和 linting： npm run typecheck && npm run lint
提交拉取请求

执照

麻省理工学院

OpenAPI MCP Server