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！
获取指定接口的参数和返回值类型信息
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | 接口路径，如 /api/channelType/list | |
| method | Yes | HTTP 方法，如 GET, POST, PUT, DELETE |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so the description carries the full burden of behavioral disclosure. It states only that the tool retrieves parameter and return-type information; it does not mention read-only behavior, authentication requirements, error handling, rate limits, or response structure. The description is not misleading, but it reveals very little beyond the core action.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that front-loads the action and the target information. No filler, repetition, or irrelevant detail—ideal for a simple two-parameter lookup tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a basic retrieval tool, the description covers the main purpose and mentions return-type information, while the schema fully handles parameters. However, with no annotations and no usage alternatives or behavioral caveats, there are notable gaps: when to choose this over getApis and what the exact response contains. It is adequate but not fully complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage for parameters is 100%, and both path and method have descriptive property definitions. The description adds little semantic meaning beyond the schema, since '指定接口' already implies the path/method combination. Baseline of 3 is appropriate when the schema fully documents parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description '获取指定接口的参数和返回值类型信息' states a clear action (获取) and resource (指定接口的参数和返回值类型信息), so an agent knows this tool retrieves parameter and return-type details for a specific API. It does not explicitly name sibling tools, but the phrase '指定接口' implies a single-API lookup, giving some implicit differentiation from getApis and getModules.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus getApis or getModules, nor does it mention exclusions or prerequisites. An agent must infer usage purely from the tool name and description, leaving the choice between getApi and getApis ambiguous.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
获取指定模块下的所有接口列表
| Name | Required | Description | Default |
|---|---|---|---|
| module | Yes | 模块名称 |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description must fully disclose behavior. It indicates a read-style operation via '获取' and that it returns a list of APIs, but it does not mention output structure, pagination, error behavior, or whether the module name must already exist. This leaves meaningful behavioral gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single compact sentence with no filler. It front-loads the action ('获取') and states the exact scoped resource, making it efficient and easy to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple one-parameter list tool, the description plus schema provide a usable minimum: call with a module name and get a list of APIs. However, it does not explain where valid module names come from, what the returned interface items look like, or how it relates to the sibling tools, so some context is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already covers the single parameter fully: 'module' is required and described as '模块名称'. The description says '指定模块下' but adds no extra semantic detail beyond the schema, so the baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies a get operation on a resource ('指定模块下的所有接口列表') and implies a list result. It is distinguishable from sibling 'getApi' through the plural '所有接口' and from 'getModules' by targeting APIs rather than modules, though it does not explicitly reference these siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is given on when to use this tool versus 'getApi' or 'getModules'. There are no exclusions, prerequisites, or explicit alternative conditions, so the agent has to infer usage purely from the tool name and one-line purpose.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
获取 Swagger API 的所有模块列表
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, and the description only says it retrieves a list, which implies read-only behavior. It does not disclose return format, pagination, potential errors, or whether modules are global or tied to a specific API.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence with no redundant wording. The action verb and resource are front-loaded, making it easy for an agent to parse quickly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter tool, the description adequately states what it returns, but the lack of output schema and absence of relationship to sibling tools leaves ambiguity about module scope and how it connects to getApi/getApis. An agent may need more context to decide when this tool is the right choice.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so the schema already fully covers parameter semantics. The baseline for zero-parameter tools is 4 because there is no parameter information needed beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description specifies a clear action ('获取') and resource ('Swagger API 的所有模块列表'), which distinguishes it from the sibling tools getApis and getApi that deal with APIs rather than modules. However, it does not explicitly contrast those alternatives, so the differentiation relies on the resource term itself.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance about when to use this tool versus getApis or getApi, nor any mention of prerequisites or context. The description only states the operation, leaving the agent to infer usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.4.2getApigetApisgetModulesScored 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.
MCP server for AI access to SmartBear tools, including BugSnag, Reflect, Swagger, PactFlow, QTM4J.
The Cortex MCP server provides read-only access to real-time engineering context from the Cortex developer portal, allowing AI coding assistants to answer natural language questions about your organization's catalog (microservices, libraries, domains, teams, infrastructure), scorecards (engineering standards and best practices), initiatives (goals and deadlines), and Engineering Intelligence metrics. It includes tools for querying documentation, tracking personal entities, and accessing AI-assisted insights across the entire Cortex ecosystem.
