{"id":28918363,"url":"https://github.com/zaizaizhao/mcp-swagger-server","last_synced_at":"2026-01-20T17:34:52.291Z","repository":{"id":300201681,"uuid":"1002418944","full_name":"zaizaizhao/mcp-swagger-server","owner":"zaizaizhao","description":"A Model Context Protocol (MCP) server for Swagger/OpenAPI documentation that transforms OpenAPI specifications into MCP format, enabling AI assistants to interact with REST APIs through standardized protocol.","archived":false,"fork":false,"pushed_at":"2025-06-20T10:45:39.000Z","size":350,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-06-20T11:38:42.552Z","etag":null,"topics":["mcp","mcp-server","openapi","swagger"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/zaizaizhao.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-06-15T12:43:01.000Z","updated_at":"2025-06-20T10:45:42.000Z","dependencies_parsed_at":"2025-06-20T11:50:12.180Z","dependency_job_id":null,"html_url":"https://github.com/zaizaizhao/mcp-swagger-server","commit_stats":null,"previous_names":["zaizaizhao/mcp-swagger-server"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/zaizaizhao/mcp-swagger-server","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zaizaizhao%2Fmcp-swagger-server","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zaizaizhao%2Fmcp-swagger-server/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zaizaizhao%2Fmcp-swagger-server/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zaizaizhao%2Fmcp-swagger-server/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/zaizaizhao","download_url":"https://codeload.github.com/zaizaizhao/mcp-swagger-server/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zaizaizhao%2Fmcp-swagger-server/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":261224293,"owners_count":23126930,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["mcp","mcp-server","openapi","swagger"],"created_at":"2025-06-22T02:02:48.724Z","updated_at":"2026-01-20T17:34:52.284Z","avatar_url":"https://github.com/zaizaizhao.png","language":"TypeScript","funding_links":[],"categories":["Developer Tools","📚 Projects (1974 total)","پیاده‌سازی‌های سرور","📦 Other","💻 Developer Tools (164 servers)","Server Implementations"],"sub_categories":["OpenAPI","MCP Servers","💻 \u003ca name=\"developer-tools\"\u003e\u003c/a\u003eابزارهای توسعه‌دهنده","💻 \u003ca name=\"developer-tools\"\u003e\u003c/a\u003eDeveloper Tools"],"readme":"# MCP Swagger Server(mss)\n\n\u003cdiv align=\"center\"\u003e\n\n[![TypeScript](https://img.shields.io/badge/TypeScript-5+-blue.svg)](https://www.typescriptlang.org/)\n[![Node.js](https://img.shields.io/badge/Node.js-16+-green.svg)](https://nodejs.org/)\n[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)\n[![Trust Score](https://archestra.ai/mcp-catalog/api/badge/quality/zaizaizhao/mcp-swagger-server)](https://archestra.ai/mcp-catalog/zaizaizhao__mcp-swagger-server)\n\n**一个将 OpenAPI/Swagger 规范转换为 Model Context Protocol (MCP) 格式的工具**\n\n零配置将您的 REST API 转换为 AI 可调用的工具\n\n[🚀 快速开始](#快速开始) • [📖 使用指南](#使用指南) • [🛠️ 开发](#开发)\n\n**Languages**: [English](README_EN.md) | 中文\n\n\u003c/div\u003e\n\n---\n## 🎯 项目截图\n\n![项目截图](./docs/img/mss.png)\n![项目截图](./docs/img/ui.png)\n## 🎯 项目简介\n\nMCP Swagger Server 是一个将 OpenAPI/Swagger 规范转换为 Model Context Protocol (MCP) 格式的工具。\n\n### 📦 项目结构\n\n```\nmcp-swagger-server/\n├── packages/\n│   ├── mcp-swagger-server/     # 🔧 核心 MCP 服务器 (可用)\n│   ├── mcp-swagger-parser/     # 📝 OpenAPI 解析器 (可用)\n│   ├── mcp-swagger-ui/         # 🎨 Web 界面 (开发中)\n│   └── mcp-swagger-api/        # 🔗 REST API 后端 (可用)\n└── scripts/                    # 🔨 构建脚本\n```\n\n### ✨ 核心特性\n\n- **🔄 零配置转换**: 输入 OpenAPI 规范，立即获得 MCP 工具\n- **🎯 渐进式命令行**: 提供逐步引导的命令行界面，方便用户配置\n- **🔌 多传输协议**: 支持 SSE、Streamable 和 Stdio 传输\n- **🔐 安全认证**: 支持 Bearer Token 认证保护 API 访问\n\n## 🚀 快速开始\n\n### 环境要求\n\n- Node.js ≥ 20.0.0\n- pnpm ≥ 8.0.0 (推荐)\n\n### 安装\n\n```bash\nnpm i mcp-swagger-server -g\n```\n\n### 快速启动\n#### 自定义启动\n```bash \nmss\n```\n#### 一键启动\n```bash \nmss --openapi https://api.example.com/openapi.json --operation-filter-methods GET,POST --transport streamable -auth-type bearer --bearer-token \"your-token-here\"\n\n# 使用配置文件\nmcp-swagger-server --config config.json\n```\n\n#### 命令行选项\n\n```bash\n# 基本用法\nmss [选项]\n\n# 选项：\n--openapi, -o       OpenAPI 规范的 URL 或文件路径\n--transport, -t     传输协议 (stdio|sse|streamable)\n--port, -p          端口号\n--watch, -w         监控文件变化\n--verbose           详细日志输出\n\n# Bearer Token 认证选项：\n--auth-type         认证类型 (bearer)\n--bearer-token      直接指定 Bearer Token\n--bearer-env        从环境变量读取 Token\n--config, -c        配置文件路径\n\n# 操作过滤选项：\n--operation-filter-methods \u003cmethods\u003e        HTTP方法过滤 (可重复) [示例: GET,POST]\n--operation-filter-paths \u003cpaths\u003e            路径过滤 (支持通配符, 可重复) [示例: /api/*]\n--operation-filter-operation-ids \u003cids\u003e      操作ID过滤 (可重复) [示例: getUserById]\n--operation-filter-status-codes \u003ccodes\u003e     状态码过滤 (可重复) [示例: 200,201]\n--operation-filter-parameters \u003cparams\u003e      参数过滤 (可重复) [示例: userId,name]\n```\n\n### 🔐 Bearer Token 认证\n\n`mcp-swagger-server` 支持 Bearer Token 认证，可以保护需要身份验证的 API 访问。\n\n#### 认证方式\n\n**1. 直接指定 Token**\n```bash\nmss --auth-type bearer --bearer-token \"your-token-here\" --openapi https://api.example.com/openapi.json --transport streamable\n```\n\n\n\n#### 环境变量配置\n\n创建 `.env` 文件：\n```env\n# 基础配置\nMCP_PORT=3322\nMCP_TRANSPORT=stdio\nMCP_OPENAPI_URL=https://api.example.com/openapi.json\n\n# 认证配置\nMCP_AUTH_TYPE=bearer\nAPI_TOKEN=your-bearer-token-here\n```\n\n### 🤖 与 AI 助手集成\n\n#### Claude Desktop 配置\n\n```json\n{\n  \"mcpServers\": {\n    \"swagger-converter\": {\n      \"command\": \"mss\",\n      \"args\": [\n        \"--openapi\", \"https://petstore.swagger.io/v2/swagger.json\",\n        \"--transport\", \"stdio\"\n      ]\n    },\n    \"secured-api\": {\n      \"command\": \"mss\",\n      \"args\": [\n        \"--openapi\", \"https://api.example.com/openapi.json\",\n        \"--transport\", \"stdio\",\n        \"--auth-type\", \"bearer\",\n        \"--bearer-env\", \"API_TOKEN\"\n      ],\n      \"env\": {\n        \"API_TOKEN\": \"your-bearer-token-here\"\n      }\n    }\n  }\n}\n```\n\n## 🛠️ 开发\n\n### 构建系统\n\n```bash\n# 构建所有包\npnpm build\n\n# 仅构建后端包\npnpm build:packages\n\n# 开发模式\npnpm dev\n\n# 清理构建产物\npnpm clean\n```\n## 🤝 贡献\n\n欢迎贡献！请先阅读 [贡献指南](CONTRIBUTING.md)。\n\n## 📄 许可证\n\nMIT License - 详见 [LICENSE](LICENSE) 文件。\n\n---\n\n\u003cdiv align=\"center\"\u003e\n\n**Built with ❤️ by ZhaoYaNan(ZTE)**\n\n[⭐ Star](../../stargazers) • [🐛 Issues](../../issues) • [💬 Discussions](../../discussions)\n\n\u003c/div\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzaizaizhao%2Fmcp-swagger-server","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fzaizaizhao%2Fmcp-swagger-server","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzaizaizhao%2Fmcp-swagger-server/lists"}