1. 服务概述一句话简介将OpenAPI端点暴露为MCP工具让大语言模型通过MCP协议发现和交互REST API服务名称OpenAPI MCP Server版本号最新版本开发者/提供方ivo-toby协议类型MCP (Model Context Protocol)2. 核心功能列出该MCP服务提供的主要功能点OpenAPI集成自动工具生成根据OpenAPI规范自动将API端点转换为MCP工具规范解析支持从URL、文件路径、标准输入或内联字符串读取OpenAPI规范动态发现LLM可以自动发现和了解REST API的功能和参数传输方式Stdio Transport通过标准输入输出直接集成适用于Claude Desktop等AI系统HTTP Transport通过HTTP连接支持Web客户端和其他HTTP系统使用MCP协议认证支持API Headers支持自定义API请求头如Bearer Token、API Key等双向TLS (mTLS)支持客户端证书认证提供企业级安全保障自定义CA证书支持私有/内部CA证书适配企业环境使用方式CLI工具通过npx直接使用快速配置和启动库集成可作为Node.js库导入用于创建自定义MCP服务器扩展功能MCP Prompts可选支持MCP提示功能MCP Resources可选支持MCP资源功能3. 使用场景描述该服务适合在什么情况下使用典型应用场景AI助手API集成让Claude等AI助手直接访问和操作REST API无需手动编写集成代码API自动发现LLM自动了解API的功能、参数和返回值智能调用APIAPI测试与调试通过自然语言描述测试API端点快速验证API功能API文档生成基于OpenAPI规范生成可交互的API文档企业API管理统一管理企业内部API让AI助手安全访问微服务集成快速集成多个微服务API构建AI驱动的应用API迁移辅助帮助AI助手理解和迁移旧API到新API4. 接入方式4.1 服务端点OpenAPI MCP Server支持两种传输方式Stdio Transport默认适用场景Claude Desktop、Cursor等直接管理MCP连接的AI系统通信方式通过标准输入输出stdin/stdout优势无需网络配置直接集成HTTP Transport适用场景Web客户端和其他HTTP系统默认端口3000可配置端点http://localhost:3000/mcp特性支持Server-Sent Events (SSE)流式响应4.2 认证与权限OpenAPI MCP Server提供多种认证方式API Headers认证格式逗号分隔的key:value对示例Authorization:Bearer token123,X-API-Key:your-api-key用途Bearer Token、API Key等标准认证双向TLS (mTLS)认证CLIENT_CERT_PATH客户端证书PEM文件路径CLIENT_KEY_PATH客户端私钥PEM文件路径CLIENT_KEY_PASSPHRASE加密私钥的密码可选CA_CERT_PATH自定义CA证书PEM文件路径REJECT_UNAUTHORIZED是否拒绝不受信任的服务器证书默认true安全提示请妥善保管所有认证凭证不要将API密钥和证书提交到版本控制系统。对于生产环境建议使用mTLS认证。4.3 数据格式OpenAPI MCP Server支持多种OpenAPI规范输入方式URL方式从HTTP/HTTPS URL加载OpenAPI规范文件路径从本地文件系统加载OpenAPI规范标准输入从stdin读取OpenAPI规范内联字符串直接提供OpenAPI规范内容支持的OpenAPI版本OpenAPI 3.0.x和3.1.x4.4 服务器配置配置1Claude DesktopStdio Transport{ 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 } } } }配置2HTTP Transport命令行npx ivotoby/openapi-mcp-server \ --api-base-url https://api.example.com \ --openapi-spec https://api.example.com/openapi.json \ --headers Authorization:Bearer token123 \ --transport http \ --port 3000配置3使用mTLS认证{ 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, CLIENT_CERT_PATH: /path/to/client-cert.pem, CLIENT_KEY_PATH: /path/to/client-key.pem, CA_CERT_PATH: /path/to/ca-cert.pem } } } }配置4从标准输入读取OpenAPI规范cat openapi.json | npx ivotoby/openapi-mcp-server \ --api-base-url https://api.example.com \ --openapi-spec-stdin5. 接口定义OpenAPI MCP Server根据OpenAPI规范自动生成MCP工具5.1 环境变量配置环境变量说明是否必需默认值API_BASE_URLAPI端点的基础URL必需-OPENAPI_SPEC_PATHOpenAPI规范的URL或路径必需*-OPENAPI_SPEC_FROM_STDIN从标准输入读取OpenAPI规范可选falseOPENAPI_SPEC_INLINE内联提供OpenAPI规范内容可选-API_HEADERSAPI请求头逗号分隔的key:value对可选-CLIENT_CERT_PATH客户端证书PEM文件路径可选-CLIENT_KEY_PATH客户端私钥PEM文件路径可选-CA_CERT_PATH自定义CA证书PEM文件路径可选-CLIENT_KEY_PASSPHRASE加密私钥的密码可选-REJECT_UNAUTHORIZED是否拒绝不受信任的服务器证书可选trueSERVER_NAMEMCP服务器名称可选mcp-openapi-serverSERVER_VERSION服务器版本可选1.0.0TRANSPORT_TYPE传输类型stdio或http可选stdioHTTP_PORTHTTP传输的端口可选3000HTTP_HOSTHTTP传输的主机可选localhost*注OPENAPI_SPEC_PATH、OPENAPI_SPEC_FROM_STDIN和OPENAPI_SPEC_INLINE三选一。5.2 HTTP Transport使用示例# 初始化会话首次请求 curl -X POST http://localhost:3000/mcp \ -H Content-Type: application/json \ -d {jsonrpc:2.0,id:0,method:initialize,params:{protocolVersion:2025-03-26,capabilities:{},clientInfo:{name:curl-client,version:1.0.0}}} # 响应包含Mcp-Session-Id头后续请求必须使用 # 列出工具 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} # 打开流式连接用于接收服务器响应 curl -N http://localhost:3000/mcp -H Mcp-Session-Id: your-session-id # 执行工具 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: {}}} # 终止会话 curl -X DELETE http://localhost:3000/mcp -H Mcp-Session-Id: your-session-id6. 快速开始6.1 环境要求Node.js需要安装Node.js环境OpenAPI规范需要有效的OpenAPI 3.0.x或3.1.x规范文件API访问权限需要目标API的访问权限和认证凭证MCP客户端Claude Desktop、Cursor或其他支持MCP的工具6.2 示例代码快速启动Claude Desktop# 1. 定位或创建Claude Desktop配置文件 # macOS: ~/Library/Application Support/Claude/claude_desktop_config.json # Windows: %APPDATA%\Claude\claude_desktop_config.json # 2. 添加以下配置 { 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 YOUR_TOKEN } } } } # 3. 重启Claude Desktop # 4. 开始使用自然语言与API交互快速启动HTTP Transport# 启动HTTP服务器 npx ivotoby/openapi-mcp-server \ --api-base-url https://api.example.com \ --openapi-spec https://api.example.com/openapi.json \ --headers Authorization:Bearer YOUR_TOKEN \ --transport http \ --port 3000 # 服务器将在 http://localhost:3000/mcp 提供服务使用示例# 示例1获取用户列表 用户指令获取所有用户的列表 AI行为自动调用GET /users端点并返回结果 # 示例2创建新用户 用户指令创建一个新用户姓名为张三邮箱为zhangsanexample.com AI行为自动调用POST /users端点并传入正确的参数 # 示例3查询特定资源 用户指令获取ID为123的用户详情 AI行为自动调用GET /users/123端点 # 示例4更新资源 用户指令将ID为123的用户邮箱更新为newemailexample.com AI行为自动调用PUT /users/123端点并传入更新数据 # 示例5删除资源 用户指令删除ID为123的用户 AI行为自动调用DELETE /users/123端点作为库使用// 在Node.js应用中使用 import { OpenAPIServer } from ivotoby/openapi-mcp-server; const server new OpenAPIServer({ apiBaseUrl: https://api.example.com, openapiSpecPath: https://api.example.com/openapi.json, apiHeaders: { Authorization: Bearer YOUR_TOKEN } }); // 启动服务器 await server.start();7. 注意事项重要限制和注意事项OpenAPI规范要求必须提供有效的OpenAPI 3.0.x或3.1.x规范确保规范完整且准确认证安全妥善保管所有认证凭证不要将API密钥和证书提交到版本控制系统API权限确保API账户具有执行所需操作的足够权限网络访问确保能够访问目标API和OpenAPI规范的网络连接速率限制注意目标API的速率限制避免过度请求HTTPS要求生产环境建议使用HTTPS确保数据传输安全mTLS配置使用mTLS时确保证书和私钥文件路径正确权限设置合理错误处理AI助手会自动处理API错误但复杂操作可能需要人工干预API兼容性确保OpenAPI规范与实际API保持同步避免调用失败测试环境建议先在测试环境中验证功能再应用于生产环境HTTP Transport会话使用HTTP Transport时必须正确管理会话ID确保请求正确路由标准输入限制从stdin读取OpenAPI规范时确保数据格式正确且完整
OpenAPI MCP Server 服务说明文档
发布时间:2026/6/5 4:41:43
1. 服务概述一句话简介将OpenAPI端点暴露为MCP工具让大语言模型通过MCP协议发现和交互REST API服务名称OpenAPI MCP Server版本号最新版本开发者/提供方ivo-toby协议类型MCP (Model Context Protocol)2. 核心功能列出该MCP服务提供的主要功能点OpenAPI集成自动工具生成根据OpenAPI规范自动将API端点转换为MCP工具规范解析支持从URL、文件路径、标准输入或内联字符串读取OpenAPI规范动态发现LLM可以自动发现和了解REST API的功能和参数传输方式Stdio Transport通过标准输入输出直接集成适用于Claude Desktop等AI系统HTTP Transport通过HTTP连接支持Web客户端和其他HTTP系统使用MCP协议认证支持API Headers支持自定义API请求头如Bearer Token、API Key等双向TLS (mTLS)支持客户端证书认证提供企业级安全保障自定义CA证书支持私有/内部CA证书适配企业环境使用方式CLI工具通过npx直接使用快速配置和启动库集成可作为Node.js库导入用于创建自定义MCP服务器扩展功能MCP Prompts可选支持MCP提示功能MCP Resources可选支持MCP资源功能3. 使用场景描述该服务适合在什么情况下使用典型应用场景AI助手API集成让Claude等AI助手直接访问和操作REST API无需手动编写集成代码API自动发现LLM自动了解API的功能、参数和返回值智能调用APIAPI测试与调试通过自然语言描述测试API端点快速验证API功能API文档生成基于OpenAPI规范生成可交互的API文档企业API管理统一管理企业内部API让AI助手安全访问微服务集成快速集成多个微服务API构建AI驱动的应用API迁移辅助帮助AI助手理解和迁移旧API到新API4. 接入方式4.1 服务端点OpenAPI MCP Server支持两种传输方式Stdio Transport默认适用场景Claude Desktop、Cursor等直接管理MCP连接的AI系统通信方式通过标准输入输出stdin/stdout优势无需网络配置直接集成HTTP Transport适用场景Web客户端和其他HTTP系统默认端口3000可配置端点http://localhost:3000/mcp特性支持Server-Sent Events (SSE)流式响应4.2 认证与权限OpenAPI MCP Server提供多种认证方式API Headers认证格式逗号分隔的key:value对示例Authorization:Bearer token123,X-API-Key:your-api-key用途Bearer Token、API Key等标准认证双向TLS (mTLS)认证CLIENT_CERT_PATH客户端证书PEM文件路径CLIENT_KEY_PATH客户端私钥PEM文件路径CLIENT_KEY_PASSPHRASE加密私钥的密码可选CA_CERT_PATH自定义CA证书PEM文件路径REJECT_UNAUTHORIZED是否拒绝不受信任的服务器证书默认true安全提示请妥善保管所有认证凭证不要将API密钥和证书提交到版本控制系统。对于生产环境建议使用mTLS认证。4.3 数据格式OpenAPI MCP Server支持多种OpenAPI规范输入方式URL方式从HTTP/HTTPS URL加载OpenAPI规范文件路径从本地文件系统加载OpenAPI规范标准输入从stdin读取OpenAPI规范内联字符串直接提供OpenAPI规范内容支持的OpenAPI版本OpenAPI 3.0.x和3.1.x4.4 服务器配置配置1Claude DesktopStdio Transport{ 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 } } } }配置2HTTP Transport命令行npx ivotoby/openapi-mcp-server \ --api-base-url https://api.example.com \ --openapi-spec https://api.example.com/openapi.json \ --headers Authorization:Bearer token123 \ --transport http \ --port 3000配置3使用mTLS认证{ 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, CLIENT_CERT_PATH: /path/to/client-cert.pem, CLIENT_KEY_PATH: /path/to/client-key.pem, CA_CERT_PATH: /path/to/ca-cert.pem } } } }配置4从标准输入读取OpenAPI规范cat openapi.json | npx ivotoby/openapi-mcp-server \ --api-base-url https://api.example.com \ --openapi-spec-stdin5. 接口定义OpenAPI MCP Server根据OpenAPI规范自动生成MCP工具5.1 环境变量配置环境变量说明是否必需默认值API_BASE_URLAPI端点的基础URL必需-OPENAPI_SPEC_PATHOpenAPI规范的URL或路径必需*-OPENAPI_SPEC_FROM_STDIN从标准输入读取OpenAPI规范可选falseOPENAPI_SPEC_INLINE内联提供OpenAPI规范内容可选-API_HEADERSAPI请求头逗号分隔的key:value对可选-CLIENT_CERT_PATH客户端证书PEM文件路径可选-CLIENT_KEY_PATH客户端私钥PEM文件路径可选-CA_CERT_PATH自定义CA证书PEM文件路径可选-CLIENT_KEY_PASSPHRASE加密私钥的密码可选-REJECT_UNAUTHORIZED是否拒绝不受信任的服务器证书可选trueSERVER_NAMEMCP服务器名称可选mcp-openapi-serverSERVER_VERSION服务器版本可选1.0.0TRANSPORT_TYPE传输类型stdio或http可选stdioHTTP_PORTHTTP传输的端口可选3000HTTP_HOSTHTTP传输的主机可选localhost*注OPENAPI_SPEC_PATH、OPENAPI_SPEC_FROM_STDIN和OPENAPI_SPEC_INLINE三选一。5.2 HTTP Transport使用示例# 初始化会话首次请求 curl -X POST http://localhost:3000/mcp \ -H Content-Type: application/json \ -d {jsonrpc:2.0,id:0,method:initialize,params:{protocolVersion:2025-03-26,capabilities:{},clientInfo:{name:curl-client,version:1.0.0}}} # 响应包含Mcp-Session-Id头后续请求必须使用 # 列出工具 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} # 打开流式连接用于接收服务器响应 curl -N http://localhost:3000/mcp -H Mcp-Session-Id: your-session-id # 执行工具 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: {}}} # 终止会话 curl -X DELETE http://localhost:3000/mcp -H Mcp-Session-Id: your-session-id6. 快速开始6.1 环境要求Node.js需要安装Node.js环境OpenAPI规范需要有效的OpenAPI 3.0.x或3.1.x规范文件API访问权限需要目标API的访问权限和认证凭证MCP客户端Claude Desktop、Cursor或其他支持MCP的工具6.2 示例代码快速启动Claude Desktop# 1. 定位或创建Claude Desktop配置文件 # macOS: ~/Library/Application Support/Claude/claude_desktop_config.json # Windows: %APPDATA%\Claude\claude_desktop_config.json # 2. 添加以下配置 { 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 YOUR_TOKEN } } } } # 3. 重启Claude Desktop # 4. 开始使用自然语言与API交互快速启动HTTP Transport# 启动HTTP服务器 npx ivotoby/openapi-mcp-server \ --api-base-url https://api.example.com \ --openapi-spec https://api.example.com/openapi.json \ --headers Authorization:Bearer YOUR_TOKEN \ --transport http \ --port 3000 # 服务器将在 http://localhost:3000/mcp 提供服务使用示例# 示例1获取用户列表 用户指令获取所有用户的列表 AI行为自动调用GET /users端点并返回结果 # 示例2创建新用户 用户指令创建一个新用户姓名为张三邮箱为zhangsanexample.com AI行为自动调用POST /users端点并传入正确的参数 # 示例3查询特定资源 用户指令获取ID为123的用户详情 AI行为自动调用GET /users/123端点 # 示例4更新资源 用户指令将ID为123的用户邮箱更新为newemailexample.com AI行为自动调用PUT /users/123端点并传入更新数据 # 示例5删除资源 用户指令删除ID为123的用户 AI行为自动调用DELETE /users/123端点作为库使用// 在Node.js应用中使用 import { OpenAPIServer } from ivotoby/openapi-mcp-server; const server new OpenAPIServer({ apiBaseUrl: https://api.example.com, openapiSpecPath: https://api.example.com/openapi.json, apiHeaders: { Authorization: Bearer YOUR_TOKEN } }); // 启动服务器 await server.start();7. 注意事项重要限制和注意事项OpenAPI规范要求必须提供有效的OpenAPI 3.0.x或3.1.x规范确保规范完整且准确认证安全妥善保管所有认证凭证不要将API密钥和证书提交到版本控制系统API权限确保API账户具有执行所需操作的足够权限网络访问确保能够访问目标API和OpenAPI规范的网络连接速率限制注意目标API的速率限制避免过度请求HTTPS要求生产环境建议使用HTTPS确保数据传输安全mTLS配置使用mTLS时确保证书和私钥文件路径正确权限设置合理错误处理AI助手会自动处理API错误但复杂操作可能需要人工干预API兼容性确保OpenAPI规范与实际API保持同步避免调用失败测试环境建议先在测试环境中验证功能再应用于生产环境HTTP Transport会话使用HTTP Transport时必须正确管理会话ID确保请求正确路由标准输入限制从stdin读取OpenAPI规范时确保数据格式正确且完整