MCP Swagger Server(mss)

一个将 OpenAPI/Swagger 规范转换为 Model Context Protocol (MCP) 格式的工具

零配置将您的 REST API 转换为 AI 可调用的工具

🚀 快速开始 • 📖 使用指南 • 🛠️ 开发

Languages: English | 中文

---

🎯 项目截图

🎯 项目简介

MCP Swagger Server 是一个将 OpenAPI/Swagger 规范转换为 Model Context Protocol (MCP) 格式的工具。

📦 项目结构

mcp-swagger-server/
├── packages/
│   ├── mcp-swagger-server/     # 🔧 核心 MCP 服务器 (可用)
│   ├── mcp-swagger-parser/     # 📝 OpenAPI 解析器 (可用)
│   ├── mcp-swagger-ui/         # 🎨 Web 界面 (开发中)
│   └── mcp-swagger-api/        # 🔗 REST API 后端 (可用)
└── scripts/                    # 🔨 构建脚本

✨ 核心特性

• 🔄 零配置转换: 输入 OpenAPI 规范，立即获得 MCP 工具
• 🎯 渐进式命令行: 提供逐步引导的命令行界面，方便用户配置
• 🔌 多传输协议: 支持 SSE、Streamable 和 Stdio 传输
• 🔐 安全认证: 支持 Bearer Token 认证保护 API 访问

🚀 快速开始

环境要求

• Node.js ≥ 20.0.0
• pnpm ≥ 8.0.0 (推荐)

安装

npm i mcp-swagger-server -g

快速启动

自定义启动

mss

一键启动

mss --openapi https://api.example.com/openapi.json --operation-filter-methods GET,POST --transport streamable -auth-type bearer --bearer-token "your-token-here"

# 使用配置文件
mcp-swagger-server --config config.json

命令行选项

# 基本用法
mss [选项]

# 选项：
--openapi, -o       OpenAPI 规范的 URL 或文件路径
--transport, -t     传输协议 (stdio|sse|streamable)
--port, -p          端口号
--watch, -w         监控文件变化
--verbose           详细日志输出

# Bearer Token 认证选项：
--auth-type         认证类型 (bearer)
--bearer-token      直接指定 Bearer Token
--bearer-env        从环境变量读取 Token
--config, -c        配置文件路径

# 操作过滤选项：
--operation-filter-methods <methods>        HTTP方法过滤 (可重复) [示例: GET,POST]
--operation-filter-paths <paths>            路径过滤 (支持通配符, 可重复) [示例: /api/*]
--operation-filter-operation-ids <ids>      操作ID过滤 (可重复) [示例: getUserById]
--operation-filter-status-codes <codes>     状态码过滤 (可重复) [示例: 200,201]
--operation-filter-parameters <params>      参数过滤 (可重复) [示例: userId,name]

🔐 Bearer Token 认证

mcp-swagger-server 支持 Bearer Token 认证，可以保护需要身份验证的 API 访问。

认证方式

1. 直接指定 Token

mss --auth-type bearer --bearer-token "your-token-here" --openapi https://api.example.com/openapi.json --transport streamable

环境变量配置

创建 .env 文件：

# 基础配置
MCP_PORT=3322
MCP_TRANSPORT=stdio
MCP_OPENAPI_URL=https://api.example.com/openapi.json

# 认证配置
MCP_AUTH_TYPE=bearer
API_TOKEN=your-bearer-token-here

🤖 与 AI 助手集成

Claude Desktop 配置

{
  "mcpServers": {
    "swagger-converter": {
      "command": "mss",
      "args": [
        "--openapi", "https://petstore.swagger.io/v2/swagger.json",
        "--transport", "stdio"
      ]
    },
    "secured-api": {
      "command": "mss",
      "args": [
        "--openapi", "https://api.example.com/openapi.json",
        "--transport", "stdio",
        "--auth-type", "bearer",
        "--bearer-env", "API_TOKEN"
      ],
      "env": {
        "API_TOKEN": "your-bearer-token-here"
      }
    }
  }
}

🛠️ 开发

构建系统

# 构建所有包
pnpm build

# 仅构建后端包
pnpm build:packages

# 开发模式
pnpm dev

# 清理构建产物
pnpm clean

🤝 贡献

欢迎贡献！请先阅读 贡献指南。

📄 许可证

MIT License - 详见 LICENSE 文件。

---

Built with ❤️ by ZhaoYaNan(ZTE)

⭐ Star • 🐛 Issues • 💬 Discussions