@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

Deploy Server

security – no known vulnerabilities

license - not found

quality - confirmed to work

How are these scores calculated?

Related Resources

Need Help?

Report Issue

Tools

Related MCP Servers

Fastn Serverofficial
fastnai
-
security
A
license
-
quality
An MCP server that enables dynamic tool registration and execution based on API definitions, providing seamless integration with services like Claude.ai and Cursor.ai.
Last updated -
12
MIT License
Stock Market Research Assistant
kvssankar
-
security
F
license
-
quality
So I tried out this cool tool I saw in a LinkedIn post https://openapitools.com All you need is your API schema (OpenAPI/Swagger), and it automatically generates an MCP schema for you. You can then drop it straight into Claude Desktop (or Cursor, LangChain, etc.) and instantly start chatting with
Last updated -
1
OpenAPI to MCP Server
TykTechnologies
A
security
A
license
A
quality
A tool that creates MCP (Model Context Protocol) servers from OpenAPI/Swagger specifications, enabling AI assistants to interact with your APIs.
Last updated -
3
37
29
MIT License
Swagger MCP Server
amrsa1
A
security
A
license
A
quality
MCP server that provides tools for exploring and testing APIs through Swagger/OpenAPI documentation.
Last updated -
5
45
5
MIT License

View all related MCP servers

SwaggerMcp