Allows querying and analyzing Swagger/OpenAPI API documentation, enabling browsing of modules, listing endpoints, and retrieving detailed type information for parameters, request bodies, and responses.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@swagger-mcp-tools Show me the modules of the Swagger API"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
一个用于 Cursor 等 MCP (Model Context Protocol) 客户端的 Swagger/OpenAPI 文档查询工具。通过 MCP 协议，AI 助手可以轻松查询和分析 Swagger API 文档，获取接口类型信息。
swagger-mcp-tools 是一个 MCP 服务器，它可以将 Swagger/OpenAPI 文档转换为 MCP 工具，让 AI 助手（如 Cursor）能够：
📚 浏览和搜索 API 文档
🔍 查询接口的详细类型信息
💡 在编写代码时获取准确的 API 类型定义
🚀 提高开发效率，减少查阅文档的时间
Related MCP server: internal-swagger-mcp
🔍 模块查询 - 获取 Swagger API 的所有模块列表
📋 接口列表 - 获取指定模块下的所有接口
📝 类型信息 - 获取接口的详细类型信息（参数、请求体、响应类型）
🔄 多格式支持 - 支持 Swagger 2.0 和 OpenAPI 3.0 格式
⚙️ 灵活配置 - 支持配置文件、环境变量等多种配置方式
无需全局安装，直接使用 npx 运行：
# 无需安装，直接使用 npx
npx swagger-mcp-tools如果需要全局安装：
npm install -g swagger-mcp-tools
# 或
yarn global add swagger-mcp-toolsgit clone https://github.com/dyq086/swagger-mcp-tools.git
cd swagger-mcp-tools
npm install
npm run build构建完成后，可以使用以下方式运行：
# 直接运行构建后的文件
node dist/mcp-server.js
# 或使用 npm link 进行本地开发
npm link
swagger-mcp-tools在 Cursor 的 MCP 配置文件中（通常是 ~/.cursor/mcp.json 或项目根目录的 .cursor/mcp.json）添加：
{
"mcpServers": {
"swagger": {
"command": "npx",
"args": ["swagger-mcp-tools@latest"],
"env": {
"SWAGGER_URL": "http://your-api.com/v3/api-docs",
"SWAGGER_TOKEN": "your-token-here"
}
}
}
}在项目根目录创建 .swagger-mcp.json：
{
"swaggerUrl": "http://your-api.com/v3/api-docs",
"token": "your-token-here"
}然后在 MCP 配置中使用：
{
"mcpServers": {
"swagger": {
"command": "npx",
"args": ["swagger-mcp-tools@latest"]
}
}
}配置加载优先级从高到低：
项目配置文件 - .swagger-mcp.json 或 swagger-mcp.config.json
项目根目录查找优先级：
环境变量 SWAGGER_MCP_PROJECT_ROOT 指定的目录（如果设置）
Cursor/IDE 环境变量 WORKSPACE_FOLDER_PATHS（自动获取，无需配置）
从 process.cwd()（当前工作目录）向上查找（默认，动态获取）
从模块目录向上查找
默认环境变量 - SWAGGER_URL 和 SWAGGER_TOKEN
项目根目录环境变量说明：
SWAGGER_MCP_PROJECT_ROOT（可选）：
未设置：自动使用 WORKSPACE_FOLDER_PATHS 或 process.cwd()，动态获取，无需配置
$CWD 或 $PWD：显式使用当前工作目录
绝对路径：/path/to/project
相对路径：相对于当前工作目录的路径
WORKSPACE_FOLDER_PATHS（自动，无需配置）：
Cursor 等 IDE 会自动提供此环境变量，指向当前打开的工作区路径
如果存在，会自动使用第一个路径作为项目根目录
在项目根目录创建 .swagger-mcp.json：
{
"swaggerUrl": "http://localhost:8080/v3/api-docs",
"token": "your-api-token"
}配置 Cursor MCP（~/.cursor/mcp.json 或项目 .cursor/mcp.json）：
{
"mcpServers": {
"swagger": {
"command": "npx",
"args": ["swagger-mcp-tools@latest"]
}
}
}重启 Cursor，现在你可以在 AI 对话中询问 API 相关信息了！
💡 提示：使用
npx方式无需全局安装，npx 会自动下载并使用最新版本的包。
"获取用户管理模块的所有接口"
"查询 /api/user/list 接口的参数类型"
"获取订单创建接口的请求体结构"
获取 Swagger API 的所有模块列表。
返回示例：
[
{
"name": "用户管理",
"description": "用户相关的接口"
},
{
"name": "订单管理",
"description": "订单相关的接口"
}
]获取指定模块下的所有接口列表。
参数：
module (string) - 模块名称
返回示例：
[
{
"path": "/api/user/list",
"method": "GET",
"summary": "获取用户列表"
},
{
"path": "/api/user/create",
"method": "POST",
"summary": "创建用户"
}
]获取指定接口的参数和返回值类型信息。
参数：
path (string) - 接口路径，如 /api/user/list
method (string) - HTTP 方法，如 GET, POST, PUT, DELETE
返回示例：
{
"path": "/api/user/list",
"method": "GET",
"summary": "获取用户列表",
"description": "分页查询用户列表",
"parameters": [
{
"name": "page",
"in": "query",
"type": "integer",
"required": false
}
],
"requestBody": null,
"responseType": {
"type": "object",
"properties": {
"code": { "type": "integer" },
"data": { "type": "array", "items": { "$ref": "#/components/schemas/User" } }
}
}
}# 安装依赖
npm install
# 开发模式运行（使用 tsx 直接运行 TypeScript）
npm run dev
# 构建为 JavaScript
npm run build在开发模式下，MCP 服务器通过 stdio 通信，日志会输出到 stderr。你可以通过以下方式测试：
# 设置环境变量
export SWAGGER_URL="http://your-api.com/v3/api-docs"
export SWAGGER_TOKEN="your-token"
# 运行服务器
npm run dev# 构建项目
npm run build
# 发布到 npm（需要先登录）
npm login
npm publishswagger-mcp-tools/
├── mcp-server.ts # 主服务器文件
├── types.ts # TypeScript 类型定义
├── package.json # 项目配置
├── tsconfig.json # TypeScript 配置（用于 IDE）
├── README.md # 说明文档
├── CHANGELOG.md # 变更日志
├── LICENSE # MIT 许可证
├── .gitignore # Git 忽略文件
└── dist/ # 构建输出目录
└── mcp-server.js # 构建后的 JavaScript 文件A: MCP 服务器通过 stdio 通信，日志会输出到 stderr。如果配置正确，你应该能看到类似以下的日志：
Swagger MCP Server running on stdio
Swagger URL: http://your-api.com/v3/api-docs
Token: *** (已设置)A: 支持 Swagger 2.0 和 OpenAPI 3.0 格式。
A: 支持通过配置文件或环境变量设置 token。如果 API 需要认证，请在配置中设置 token 或 SWAGGER_TOKEN。
A: 可以。只要支持 MCP 协议的客户端都可以使用，包括 Cursor、Claude Desktop 等。
MIT License
欢迎提交 Issue 和 Pull Request！
Fork 本项目
创建特性分支 (git checkout -b feature/AmazingFeature)
提交更改 (git commit -m 'Add some AmazingFeature')
推送到分支 (git push origin feature/AmazingFeature)
开启 Pull Request
如果这个项目对你有帮助，欢迎给个 ⭐️ Star！
获取指定接口的参数和返回值类型信息
Inputs: path (required), method (required).
获取指定模块下的所有接口列表
Inputs: module (required).
获取 Swagger API 的所有模块列表
Inputs: no named parameters.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
Scored across 3 tools
每个工具对应一个明确的层级：模块列表、接口列表、接口详情，目的清晰且互不重叠。代理可以准确区分三个工具的使用场景。
三个工具均使用 get + 名词的驼峰命名模式（getModules, getApis, getApi），单复数使用合理，命名风格完全统一。
3个工具正好覆盖Swagger浏览的核心层级（模块→接口→详情），没有冗余也没有明显缺失，数量与目的匹配。
浏览流程覆盖完整，能够通过模块->接口->详情链路获取所需信息；但缺少全局接口搜索或直接查看原始Swagger定义的能力，略有小缺口。
MCP server for AI access to Swagger by SmartBear.
Pay-per-use tool marketplace for AI agents. Search, price-check, and call APIs via MCP.
Search and inspect source-pinned agent skills, plugins and tools through a free public MCP.
MCP server for AI access to SmartBear tools, including BugSnag, Reflect, Swagger, PactFlow, QTM4J.