Swagger/Postman MCP服务器
使用MCP（模型上下文协议）工具接收和提供Swagger/OpenAPI规范和Postman集合的服务器 简化战略方法.
该服务器不是为每个API端点生成数百个单独的工具，而是提供 只有4个战略工具 允许AI代理动态发现API并与之交互：
Example prompt:
Help me generate an axios call using our api mcp. I want to implement updating a user. Follow our same DDD pattern (tanstack hook -> axios service)特性
- 战略工具方法：只有4个工具，而不是数百个，可以提高AI代理的性能
- OpenAPI/Swagger支持：从URL或本地文件加载OpenAPI 2.0/3.0规范
- 邮差收藏支持：从URL或本地文件加载Postman集合JSON文件
- 环境变量：支持Postman环境文件
- 认证：多种身份验证方法（基本、承载、API密钥、OAuth2）
- 动态API发现：用于列出、搜索和获取有关API端点的详细信息的工具
- 请求执行：通过正确的参数处理和身份验证执行API请求
安全
这是个人服务器！！不要把它暴露在公共互联网上。 如果底层API需要身份验证，则不应将MCP服务器暴露于公共互联网。
TODO
- 机密-MCP服务器应该能够使用来自用户的机密来验证对API的请求
- 全面的测试套件
先决条件
- Node.js（v18或更高版本）
- 纱线包装经理
- TypeScript
安装
# Clone the repository
git clone
cd swag-mcp
# Install dependencies
npm install
# or
yarn install
# Build the project
npm run build
# or
yarn build
# Make the start script executable (Linux/macOS)
chmod +x start-mcp.sh光标快速设置
- 克隆和构建 （以上命令）
- 配置 你的
config.json与您的API详细信息 - 更新路径：编辑
start-mcp.sh并更改cd安装目录的路径 - 添加到光标：编辑
~/.cursor/mcp.json并添加：
{
"mcpServers": {
"postman-swagger-api": {
"command": "/full/path/to/your/swag-mcp/start-mcp.sh"
}
}
}- 重新启动游标 并开始使用4个战略性MCP工具！
配置
服务器使用 config.json 配置文件。您可以指定OpenAPI/Swagger规范或Postman集合。
OpenAPI/Swagger配置
{
"api": {
"type": "openapi",
"openapi": {
"url": "https://petstore.swagger.io/v2/swagger.json",
"apiBaseUrl": "https://petstore.swagger.io/v2",
"defaultAuth": {
"type": "apiKey",
"apiKey": "special-key",
"apiKeyName": "api_key",
"apiKeyIn": "header"
}
}
},
"log": {
"level": "info"
}
}邮差收集配置
{
"api": {
"type": "postman",
"postman": {
"collectionUrl": "https://www.postman.com/collections/your-collection-id",
"collectionFile": "./examples/postman-collection.json",
"environmentUrl": "https://www.postman.com/environments/your-environment-id",
"environmentFile": "./examples/postman-environment.json",
"defaultAuth": {
"type": "bearer",
"token": "your-api-token-here"
}
}
},
"log": {
"level": "info"
}
}配置选项
API配置
api.type：要么"openapi"或"postman"api.openapi：OpenAPI/Swagger特定配置
- url：指向OpenAPI规范的URL - apiBaseUrl：API请求的基本URL - defaultAuth：默认身份验证配置
api.postman：邮递员特定配置
- collectionUrl：邮递员收藏的URL（可选） - collectionFile：本地邮差收藏文件的路径（可选） - environmentUrl：Postman环境的URL（可选） - environmentFile：本地Postman环境文件的路径（可选） - defaultAuth：默认身份验证配置
验证配置
type：身份验证类型("basic","bearer","apiKey","oauth2")username：用户名（用于基本身份验证）password：密码（用于基本身份验证）token：令牌（用于承载/oauth2身份验证）apiKey：API密钥值apiKeyName：API关键参数名称apiKeyIn：将API密钥发送到何处("header"或"query")
日志记录配置
log.level：日志记录级别("debug","info","warn","error")
用法
启动MCP服务器
服务器通过用于MCP连接的stdio传输运行：
# Start the simplified MCP server via stdio
./start-mcp.sh
# Or directly with node
node dist/simple-stdio.js
# For development with auto-reload
npm run dev:simple
# or
yarn dev:simpleMCP集成
此服务器使用stdio传输，旨在与Claude Desktop或Cursor等MCP客户端一起使用。
在Cursor中安装
要将此MCP服务器与Cursor一起使用，您需要将其添加到Cursor MCP配置中：
1.找到您的Cursor MCP配置文件
配置文件位于：
- Linux/macOS:
~/.cursor/mcp.json - 视窗:
%APPDATA%\.cursor\mcp.json
2.添加MCP服务器配置
编辑您的 mcp.json 包含此服务器的文件：
{
"mcpServers": {
"postman-swagger-api": {
"command": "/path/to/your/swag-mcp/start-mcp.sh"
}
}
}⚠️ 重要提示：更改路径！
替换 /path/to/your/swag-mcp/start-mcp.sh 使用克隆存储库的实际路径。例如：
- Linux/macOS:
"/home/username/Documents/swag-mcp/start-mcp.sh" - 视窗:
"C:\\Users\\username\\Documents\\swag-mcp\\start-mcp.sh"
3.完整配置示例
{
"mcpServers": {
"supabase": {
"command": "npx",
"args": [
"-y",
"@supabase/mcp-server-supabase@latest",
"--access-token",
"your-supabase-token"
]
},
"postman-swagger-api": {
"command": "/home/username/Documents/swag-mcp/start-mcp.sh"
}
}
}4.重新启动游标
保存配置文件后，重新启动Cursor以使更改生效。
5.验证安装
在Cursor中，您现在应该可以访问4个战略MCP工具：
list_requests-列出所有可用请求get_request_details-获取详细的请求信息search_requests-按关键字搜索请求make_request-执行任何API请求
故障排除
如果MCP服务器无法启动：
- 更新start-mcp.sh路径：编辑
start-mcp.sh并更改cd路径来自/path/to/your/swag-mcp到您的实际安装目录 - 检查路径：确保路径
mcp.json指向您的实际start-mcp.sh文件 - 检查权限：确保
start-mcp.sh可执行(chmod +x start-mcp.sh) - 检查构建：确保你已经跑过了
npm run build编译TypeScript文件 - 检查日志：在Cursor的MCP日志中查找错误消息
路径更新示例
如果你克隆到 /home/username/Documents/swag-mcp/那么：
在 start-mcp.sh:
cd "/home/username/Documents/swag-mcp"在 ~/.cursor/mcp.json:
"command": "/home/username/Documents/swag-mcp/start-mcp.sh"运作原理
战略工具方法
该服务器不是为每个API端点生成数百个单独的工具，而是提供 4战略工具 实现动态API发现和交互：
OpenAPI/Swagger模式
4战略工具：
list_endpoints-列出所有可用的API端点get_endpoint_details-获取特定端点的详细信息search_endpoints-按关键字搜索端点make_api_call-使用正确的身份验证执行任何API调用
流程：
- 从配置的URL或文件加载OpenAPI规范
- 分析规范以提取API端点、参数和安全方案
- 通过4个战略工具提供端点信息
- 动态处理身份验证和参数验证
- 执行API请求并返回响应
邮递员收款模式
4战略工具：
list_requests-列出集合中所有可用的请求get_request_details-获取有关特定请求的详细信息search_requests-按关键字搜索请求make_request-执行集合中的任何请求
流程：
- 从配置的URL或文件加载Postman集合JSON
- （可选）加载Postman环境文件进行变量替换
- 解析集合中的请求、文件夹和嵌套项
- 通过4个战略工具提供请求信息
- 动态处理变量替换、身份验证和参数映射
- 使用正确的标头、查询参数和正文数据执行请求
战略工具的好处
- 更好的AI性能4个工具vs数百个工具意味着更快的决策
- 动态发现：AI代理可以在不事先知道端点的情况下探索API
- 灵活的互动：任何端点都可以通过调用
make_api_call/make_request - 减少超重：AI代理没有大量的工具选项
战略工具参考
适用于OpenAPI/Swagger API
list_endpoints
- 列出所有可用的API终结点及其方法和路径 - 无需参数 - 返回：端点摘要数组
get_endpoint_details
- 获取特定端点的详细信息 - 参数： method （GET/POST/等）， path （/users/{id}/etc） - 返回：带参数的完整端点规范、主体模式、响应
search_endpoints
- 按路径、摘要或描述中的关键字搜索端点 - 参数： query （搜索词） - 返回：匹配端点的筛选列表
make_api_call
- 对任何终结点执行API调用 - 参数： method, path, pathParams, queryParams, headers, body - 返回：带状态和数据的API响应
用于邮递员收藏
list_requests
- 列出集合中所有可用的请求 - 无需参数 - 返回：请求摘要数组
get_request_details
- 获取特定请求的详细信息 - 参数： requestId 或 requestName - 返回：完整请求规范
search_requests
- 按关键字搜索请求 - 参数： query （搜索词） - 返回：已筛选的匹配请求列表
make_request
- 执行集合中的任何请求 - 参数： requestId, variables （替换） - 返回：请求响应
认证
服务器支持多种身份验证方法：
- 基本认证：用户名/密码
- 持有者令牌：JWT或其他不记名代币
- API密钥：在标题或查询参数中
- OAuth2：基于承载令牌
身份验证可以全局配置，也可以根据请求覆盖。
配置示例
你的 config.json 应指定如上所示的OpenAPI或Postman配置。
邮差收藏结构示例
{
"info": {
"name": "Sample API Collection",
"description": "A sample Postman collection"
},
"item": [
{
"name": "Get Users",
"request": {
"method": "GET",
"header": [],
"url": {
"raw": "{{baseUrl}}/users",
"host": ["{{baseUrl}}"],
"path": ["users"]
}
}
}
]
}发展
# Install dependencies
npm install
# Run in development mode
npm run dev
# Run tests
npm test
# Build for production
npm run build许可证
国际协调委员会
环境变量
PORT：服务器端口（默认值：3000）API_USERNAME：API身份验证的用户名（回退）API_PASSWORD：API身份验证的密码（回退）API_TOKEN：用于身份验证的API令牌（回退）DEFAULT_API_BASE_URL：API终结点的默认基本URL（回退）DEFAULT_SWAGGER_URL：默认Swagger规范URL