MCP server for querying Swagger schema - get request/response schemas by API path
npm install mcp-swagger-schema一个 MCP (Model Context Protocol) 服务器,用于查询 Swagger 规范中的接口 schema。
- 根据 API 路径获取请求和响应的 JSON Schema
- 自动解析 $ref 引用
- 支持路径参数匹配(如 /api/users/{id})
- 内置缓存机制
你需要先获取项目的 Swagger/OpenAPI 规范地址,通常是类似这样的 URL:
- https://your-api.com/v3/api-docs
.mcp/config.json 或类似的配置),添加如下配置:json
{
"mcpServers": {
"swagger-schema": {
"command": "npx",
"args": ["-y", "mcp-swagger-schema"],
"env": {
"SWAGGER_SPEC_URL": "替换成你的swagger地址"
}
}
}
}
`
⚠️ 常见问题:找不到 npx 命令
如果启动失败,提示找不到
npx,按以下步骤解决:$3
`bash
which npx
`你会看到类似这样的输出:
`
/Users/你的用户名/.nvm/versions/node/v20.0.0/bin/npx
`$3
把上面输出的路径,去掉最后的
/npx,得到 bin 目录:
`
/Users/你的用户名/.nvm/versions/node/v20.0.0/bin
`$3
`json
{
"mcpServers": {
"swagger-schema": {
"command": "npx",
"args": ["-y", "mcp-swagger-schema"],
"env": {
"SWAGGER_SPEC_URL": "替换成你的swagger地址",
"PATH": "步骤2得到的路径:/usr/bin:/bin"
}
}
}
}
`例如:
`json
{
"mcpServers": {
"swagger-schema": {
"command": "npx",
"args": ["-y", "mcp-swagger-schema"],
"env": {
"SWAGGER_SPEC_URL": "https://api.example.com/swagger.json",
"PATH": "/Users/zhangsan/.nvm/versions/node/v20.0.0/bin:/usr/bin:/bin"
}
}
}
}
`---
使用方法
配置完成后,在对话中直接说:
> 获取 /api/users 接口的 schema
AI 会调用工具返回该接口的请求参数和响应结构。
$3
| 参数 | 必填 | 说明 |
|------|------|------|
|
path | ✅ | 接口路径,如 /api/users |
| method | ❌ | HTTP 方法(get/post/put/delete),不填会自动选择 |$3
`json
{
"found": true,
"path": "/api/users",
"method": "post",
"summary": "创建用户",
"request": {
"body": {
"type": "object",
"properties": {
"name": { "type": "string" },
"email": { "type": "string" }
}
}
},
"response": {
"type": "object",
"properties": {
"id": { "type": "integer" },
"name": { "type": "string" }
}
}
}
`---
环境变量
| 变量名 | 必填 | 说明 |
|--------|------|------|
|
SWAGGER_SPEC_URL | ✅ | Swagger/OpenAPI JSON 规范的 URL |
| SWAGGER_CACHE_TTL_MS` | ❌ | 缓存过期时间(毫秒),默认 60000 |MIT