@yuuzu/swagger-mcp
基於 TypeScript SDK MCP 的 Swagger/OpenAPI MCP 服務器。此工具能夠從 Swagger/OpenAPI 文檔動態生成 MCP 工具，讓 Claude Desktop 可以直接調用 REST API。
功能特色
- ✅ 支援所有 Swagger/OpenAPI 版本（2.0、3.0、3.1）
- ✅ 從 URL 或本地文件載入 Swagger 文檔
- ✅ 動態生成 MCP 工具
- ✅ 優化的工具命名格式：使用
method-path-group-endpoint格式（如：post-api-auth-signin） - ✅ 支援多種認證方式（Bearer Token、API Key、Basic Auth）
- ✅ 自動參數驗證（使用 Zod）
- ✅ 請求/回應日誌記錄
- ✅ 自動重新載入 Swagger 文檔
- ✅ 完整的錯誤處理
系統需求
- Node.js >= 20.14
安裝
# Clone 專案
# 使用 npx（推薦）
npx @yuuzu/swagger-mcp
# 或全域安裝
npm install -g @yuuzu/swagger-mcp
# 或從源碼安裝
git clone https://github.com/nakiriyuuzu/swagger-mcp.git
cd swagger-mcp
# 安裝依賴
npm install
# 建構專案
npm run build
設定
1. 環境變數設定
複製 .env.sample 並重新命名為 .env：
cp .env.sample .env
編輯 .env 檔案，設定您的 Swagger 文檔來源和認證資訊：
# Swagger 文檔來源（擇一）
SWAGGER_URL=https://api.example.com/swagger.json
# 或使用本地檔案
# SWAGGER_PATH=/path/to/swagger.json
# 認證設定
AUTH_TYPE=bearer
AUTH_TOKEN=your-jwt-token-here
# 其他選項
LOG_LEVEL=info
2. Claude Desktop 設定
在 Claude Desktop 的設定檔中加入 SwaggerMcp 服務器：
Windows: %APPDATA%\Claude\claude_desktop_config.json
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Linux: ~/.config/Claude/claude_desktop_config.json
{
"mcpServers": {
"swagger-mcp": {
"command": "npx",
"args": ["@yuuzu/swagger-mcp"],
"env": {
"SWAGGER_URL": "https://api.example.com/swagger.json",
"AUTH_TYPE": "bearer",
"AUTH_TOKEN": "your-jwt-token-here"
}
}
}
}
使用方式
- 重新啟動 Claude Desktop
- 在對話中，您可以看到從 Swagger 文檔生成的工具
- 使用工具時，Claude 會自動調用對應的 API
範例對話
User: 使用 API 登入，帳號是 test@example.com，密碼是 password123
Claude: 我會使用 post-api-auth-signin 工具來幫您登入。
[調用工具 post-api-auth-signin]
登入成功！這是您的認證資訊：
- Token: eyJhbGciOiJIUzI1NiIs...
- 過期時間: 2024-01-25T12:00:00Z
環境變數說明
必要設定
| 變數 | 說明 | 範例 |
|---|---|---|
SWAGGER_URL 或 SWAGGER_PATH | Swagger 文檔來源 | https://api.example.com/swagger.json |
認證設定
| 變數 | 說明 | 預設值 |
|---|---|---|
AUTH_TYPE | 認證類型：bearer、apikey、basic、none | none |
AUTH_TOKEN | 認證 token 或憑證 | - |
AUTH_HEADER | 認證標頭名稱 | Authorization |
API_KEY_HEADER | API Key 標頭名稱（apikey 類型） | X-API-Key |
進階設定
| 變數 | 說明 | 預設值 |
|---|---|---|
API_BASE_URL | 覆蓋 Swagger 中的 base URL（重要：如果 Swagger 使用相對 URL，必須設定此項） | - |
API_TIMEOUT | 請求超時時間（毫秒） | 30000 |
REFRESH_INTERVAL | Swagger 文檔重新載入間隔（毫秒） | 3600000 |
LOG_LEVEL | 日誌等級：debug、info、warn、error | info |
ENABLE_REQUEST_LOGGING | 啟用請求/回應日誌 | false |
API_BASE_URL 設定說明
某些 Swagger 文檔使用相對 URL 作為服務器地址（例如 /api）。在這種情況下，您需要設定 API_BASE_URL 來指定完整的 API 基礎 URL：
# 使用相對 URL 的 API 範例
SWAGGER_URL=https://example.com/api/swagger.json
API_BASE_URL=https://example.com/api
支援的認證方式
Bearer Token
AUTH_TYPE=bearer
AUTH_TOKEN=eyJhbGciOiJIUzI1NiIs...
API Key
AUTH_TYPE=apikey
AUTH_TOKEN=your-api-key
API_KEY_HEADER=X-API-Key
Basic Auth
AUTH_TYPE=basic
AUTH_TOKEN=username:password
開發
開發模式
npm run dev
執行測試
npm test
程式碼檢查
npm run lint
npm run typecheck
專案結構
SwaggerMcp/
├── src/
│ ├── index.ts # 入口點
│ ├── SwaggerMcpServer.ts # 主服務器類
│ ├── parsers/ # Swagger 解析器
│ │ ├── SwaggerParser.ts # 基礎解析器
│ │ ├── OpenApi2Parser.ts # OpenAPI 2.0 解析器
│ │ └── OpenApi3Parser.ts # OpenAPI 3.x 解析器
│ ├── generators/ # 工具生成器
│ │ ├── ToolGenerator.ts # MCP 工具生成
│ │ └── SchemaConverter.ts # Schema 轉換
│ ├── proxy/ # API 代理
│ │ ├── ApiProxy.ts # 請求代理
│ │ └── AuthManager.ts # 認證管理
│ └── utils/ # 工具函數
│ ├── config.ts # 設定管理
│ └── logger.ts # 日誌工具
├── package.json
├── tsconfig.json
└── README.md
疑難排解
無法載入 Swagger 文檔
- 確認 URL 或檔案路徑正確
- 檢查網路連線
- 確認 Swagger 文檔格式正確
認證失敗
- 確認 AUTH_TYPE 設定正確
- 檢查 token 是否過期
- 確認認證標頭名稱正確
工具未出現在 Claude Desktop
- 確認 SwaggerMcp 服務器正在執行
- 檢查 Claude Desktop 設定檔路徑
- 重新啟動 Claude Desktop
授權
MIT License