Swagger Explorer MCP
用于通过 Claude 探索和分析 Swagger/OpenAPI 规范的管理控制平面 (MCP) 服务器。
快速入门
使用 npx 全局安装并运行：
npx -y @johnneerdael/swagger-mcp
或者使用环境变量安装：
npx -y @johnneerdael/swagger-mcp \
--env BASE_URL=/api \
--env AUTH_TOKEN=your-token \
--env PORT=3000
Claude Desktop 安装
- 打开 Claude 桌面
- 点击“设置”（齿轮图标）
- 选择“工具和集成”
- 点击“添加 MCP 服务器”
- 输入以下内容：
Name: Swagger Explorer
Command: npx -y @johnneerdael/swagger-mcp
Arguments: --swagger-url=$SWAGGER_URL
- 点击“安装”
与 Claude 一起使用
以下是与 Claude 互动的一些示例：
Swagger 基本探索
Human: Can you explore the Swagger documentation at http://localhost:8080/docs?
Claude: I'll help you explore that Swagger documentation using the Swagger Explorer MCP.
Let me analyze the API endpoints and schemas for you:
[Claude would then use the MCP to fetch and analyze the Swagger documentation]
分析特定端点
Human: What are the available response schemas for the /pets POST endpoint?
Claude: I'll check the response schemas for that endpoint using the MCP.
[Claude would use the MCP to fetch specific endpoint details]
模式分析
Human: Can you show me the detailed structure of the Pet schema?
Claude: I'll retrieve the detailed schema information using the MCP.
[Claude would use the MCP to analyze the schema structure]
特征
- 身份验证支持
- 自定义响应格式
- 最小格式：删除空值
- 详细格式：包括元数据和时间戳
- 原始格式：未修改的响应
- 模式分析
- API探索
配置
环境变量：
BASE_URL ：API 的基本路径（默认值：''）AUTH_TOKEN ：用于身份验证的承载令牌PORT ：服务器端口（默认值：3000）SWAGGER_URL ：默认 Swagger 文档 URL
API 端点
探索 API
curl -X POST http://localhost:3000/api/explore \
-H "Authorization: Bearer your-token" \
-H "Content-Type: application/json" \
-d '{
"url": "http://your-swagger-url",
"options": {
"paths": true,
"schemas": true
}
}'
获取架构详细信息
curl -X POST http://localhost:3000/api/schema-details \
-H "Authorization: Bearer your-token" \
-H "Content-Type: application/json" \
-d '{
"url": "http://your-swagger-url",
"schemaName": "Pet"
}'
获取响应模式
curl -X POST http://localhost:3000/api/response-schemas \
-H "Authorization: Bearer your-token" \
-H "Content-Type: application/json" \
-d '{
"url": "http://your-swagger-url",
"path": "/pets",
"method": "post"
}'
响应格式
最小格式
{
"status": "success",
"data": {
// Only non-null values
}
}
详细格式
{
"status": "success",
"timestamp": "2025-01-29T10:00:00.000Z",
"data": {
// Full response
},
"metadata": {
"version": "1.0",
"format": "detailed"
}
}
常见用例
- API 文档审查
Human: Can you summarize all the available endpoints and their purposes?
- 模式验证
Human: What fields are required for creating a new pet?
- 响应分析
Human: What are the possible error responses for the login endpoint?
- 整合规划
Human: How should I structure my request to create a new order?
故障排除
- 连接问题
- 确保 Swagger URL 可访问
- 检查身份验证令牌是否正确
- 验证端口未被使用
- 授权错误
- 验证 AUTH_TOKEN 是否设置正确
- 确保请求中包含持有者令牌
- 未找到架构
- 检查架构名称是否完全匹配
- 验证 Swagger 规范是否已正确加载
安全说明
- 如果设置了 AUTH_TOKEN，MCP 需要身份验证
- 所有请求均已记录以供调试
- 敏感信息不被缓存
- 限制速率以防止滥用
发展
贡献或修改：
- 克隆存储库
- 安装依赖项：
- 建造：
- 本地运行：
执照
MIT 许可证 - 详情请参阅许可证文件