开放API-MCP服务器

Name: 开放API-MCP服务器
Author: FusionWorks

作者：FusionWorks2 星标更新：2025-09-24

安装使用来源：spider==github.com

项目介绍

OpenAPI MCP Server

此应用程序基于其OpenAPI模式将任何REST API暴露为MCP（模型上下文协议）服务器。它自动从OpenAPI操作生成MCP工具，并全面支持OpenAPI 3.0+。

功能

完整的OpenAPI 3.0+支持：解析来自JSON和YAML格式的模式
高级模式处理：完全解决$ref引用，组合模式（oneOf、anyOf、allOf）
丰富的工具生成：自动生成带有详细描述、验证和元数据的MCP工具
多种内容类型：支持JSON、XML、表单数据和多部分上传
参数处理：路径、查询、头部参数及其类型转换和验证
认证：HTTP基本认证和支持自定义头部
增强的错误处理：带有请求上下文的详细错误消息
类型安全：完整的TypeScript实现及全面验证
测试：覆盖90%以上的广泛测试套件

安装

npm install
npm run build

使用

npm start -- --schema <openapi模式文件路径> [选项]

选项

-s, --schema <路径> - OpenAPI模式文件路径（JSON或YAML）[必需]
-b, --base-url <URL> - 覆盖模式中的基础URL
-h, --headers <头部> - 作为JSON字符串的附加头部
-u, --username <用户名> - 基本认证的用户名
-p, --password <密码> - 基本认证的密码

示例

# 基本用法，使用本地模式文件
npm start -- --schema ./api-schema.yaml

# 覆盖基础URL
npm start -- --schema ./api-schema.json --base-url https://api.example.com

# 添加认证头部
npm start -- --schema ./api-schema.yaml --headers '{"Authorization": "Bearer your-token"}'

# 使用基本认证
npm start -- --schema ./api-schema.yaml --username myuser --password mypass

# 结合基本认证与自定义基础URL
npm start -- --schema ./api-schema.yaml --base-url https://api.example.com --username admin --password secret123

认证

HTTP基本认证

服务器通过命令行参数提供的用户名和密码支持HTTP基本认证：

npm start -- --schema ./api-schema.yaml --username myuser --password mypassword

当提供基本认证凭据时：

必须指定用户名和密码（不能只提供一个）
凭据会被base64编码并发送在Authorization: Basic <编码>头部中
所有API请求将自动包含认证头部

额外头部

您还可以使用--headers选项提供额外头部（包括自定义认证）：

npm start -- --schema ./api-schema.yaml --headers '{"Authorization": "Bearer token", "X-API-Key": "key123"}'

注意：基本认证（--username/--password）和额外头部可以一起使用。如果两者都包含授权头部，则额外头部优先。

添加到Claude Desktop

要将此MCP服务器与Claude Desktop一起使用，需要将其添加到您的Claude Desktop配置文件中。

配置文件位置

配置文件位于：

macOS：~/Library/Application Support/Claude/claude_desktop_config.json
Windows：%APPDATA%\Claude\claude_desktop_config.json

配置步骤

构建服务器（如果尚未构建）：
```
npm install
npm run build
```
打开或创建Claude Desktop配置文件，位于上述位置。

添加MCP服务器配置：

{
  "mcpServers": {
    "openapi-server": {
      "command": "node",
      "args": [
        "/path/to/your/openapi-mcp-server/dist/index.js",
        "--schema",
        "/path/to/your/openapi-schema.yaml"
      ]
    }
  }
}

替换路径为实际路径：
- 将/path/to/your/openapi-mcp-server/替换为您克隆/下载该项目的实际路径
- 将/path/to/your/openapi-schema.yaml替换为您的OpenAPI模式文件的实际路径

示例配置

这里是一些示例配置，展示了不同的认证方法：

基本认证

{
  "mcpServers": {
    "secure-api": {
      "command": "node",
      "args": [
        "/Users/username/projects/openapi-mcp-server/dist/index.js",
        "--schema",
        "/Users/username/projects/openapi-mcp-server/api-schema.yaml",
        "--username",
        "apiuser",
        "--password",
        "secret123"
      ]
    }
  }
}

Bearer令牌认证

{
  "mcpServers": {
    "xmpt-api": {
      "command": "node",
      "args": [
        "/Users/username/projects/openapi-mcp-server/dist/index.js",
        "--schema",
        "/Users/username/projects/openapi-mcp-server/schema.yaml",
        "--base-url",
        "https://api.your.service",
        "--headers",
        "{\"Authorization\": \"Bearer your-api-token\"}"
      ]
    }
  }
}

多个API配置

{
  "mcpServers": {
    "secure-api": {
      "command": "node",
      "args": [
        "/Users/username/projects/openapi-mcp-server/dist/index.js",
        "--schema",
        "/Users/username/projects/schemas/secure-api.yaml",
        "--username",
        "admin",
        "--password",
        "password123"
      ]
    },
    "public-api": {
      "command": "node",
      "args": [
        "/Users/username/projects/openapi-mcp-server/dist/index.js",
        "--schema",
        "/Users/username/projects/schemas/public-api.json"
      ]
    }
  }
}

配置选项

当将服务器添加到Claude Desktop时，您可以使用所有相同的命令行选项：

--schema <路径> - 您的OpenAPI模式文件路径（必需）
--base-url <URL> - 覆盖模式中的基础URL
--headers <json> - 以JSON字符串形式添加认证或其他头部
--username <用户名> - 基本认证的用户名
--password <密码> - 基本认证的密码

重启Claude Desktop

修改配置文件后，重启Claude Desktop使更改生效。

验证

配置并重启后，您应该能够在与Claude的对话中使用API工具。这些工具将根据您的OpenAPI模式自动生成，并包含已配置的认证。

工作原理

模式加载：加载并验证来自JSON或YAML文件的OpenAPI 3.0+模式
工具生成：为每个API操作自动生成MCP工具
认证设置：如果提供了凭据，则配置HTTP基本认证
参数映射：将OpenAPI参数映射到MCP工具输入模式
请求执行：使用提供的参数和认证执行HTTP请求
响应处理：返回格式化的响应，包括状态、头部和数据

支持的OpenAPI功能

✅ 完整的参数支持：路径、查询、头部参数及其验证
✅ 所有内容类型：JSON、XML、form-urlencoded、multipart/form-data等
✅ 高级模式特性：$ref解析、oneOf/anyOf/allOf组合、嵌套对象
✅ 类型验证：完整的JSON Schema验证，支持格式（如email、uuid等）
✅ 认证：HTTP基本认证和支持自定义头部
✅ 丰富的描述：工具描述包括摘要、标签、响应代码
✅ 错误处理：带有请求上下文的详细错误消息
✅ 类型转换：自动参数类型转换（字符串到数字/布尔值/数组）
✅ 模式规范化：自动生成缺失的操作ID和响应
✅ 多个HTTP方法：GET、POST、PUT、PATCH、DELETE、OPTIONS、HEAD

改进点

此增强版本在基本实现基础上进行了显著改进：

模式处理

完整的$ref解析：支持所有引用类型，包括嵌套和循环引用
组合模式：完全支持oneOf、anyOf、allOf，并带有描述性错误消息
验证约束：最小/最大值、字符串长度、模式、枚举及其增强描述
格式支持：内置格式验证（如email、uuid、date-time等）

工具生成

丰富的描述：结合摘要、描述、标签和响应信息
增强的元数据：存储操作元数据以改善工具执行上下文
内容类型检测：智能地优先考虑内容类型（JSON > XML > 其他）
参数验证：全面验证并带有详细错误消息

API客户端

类型转换：自动将字符串输入转换为正确的类型
内容类型处理：智能的内容类型检测和主体处理
错误增强：详细的错误消息，包括请求URL、方法和响应数据
参数处理：高级参数验证和类型强制

测试与质量

广泛的测试套件：超过90%的测试覆盖率，包括集成测试
TypeScript：整个代码库的完整类型安全
ESLint配置：代码质量强制执行
Jest配置：现代测试设置，带覆盖率报告

安全注意事项

命令行凭证：使用基本认证时，凭证通过命令行参数传递，可能会在系统进程列表中可见
Base64编码：HTTP基本认证使用标准的base64编码（非加密）
推荐使用HTTPS：传输认证凭证时始终使用HTTPS端点
环境变量：生产环境中考虑使用环境变量存储敏感凭证

开发

# 安装依赖
npm install

# 开发模式，自动重载
npm run dev -- --schema ./example-schema.yaml

# 构建项目
npm run build

# 运行测试
npm test

# 运行测试并生成覆盖率报告
npm run test:coverage

# 检查代码
npm run lint

# 修复代码检查问题
npm run lint:fix

测试

项目包括涵盖以下方面的综合测试：

单元测试：针对模式加载、工具生成和API客户端的组件单独测试
集成测试：使用复杂OpenAPI模式的端到端工作流测试
边缘案例：错误处理、循环引用、畸形模式
类型安全：整个代码库的完整TypeScript覆盖及严格类型检查

运行测试：

npm test                 # 运行所有测试
npm run test:watch       # 在监视模式下运行测试
npm run test:coverage    # 生成覆盖率报告

架构

增强实现由几个关键组件组成：

SchemaLoader：验证和规范化OpenAPI模式，带有全面的错误报告
ToolGenerator：将OpenAPI操作转换为带有丰富元数据和验证的MCP工具
APIClient：执行HTTP请求，带有自动类型转换和详细的错误处理
Server：带有工具元数据集成的MCP服务器实现

许可证

MIT