Supports generating Axios calls through an API interaction pattern, allowing AI agents to help implement API calls following domain-driven design patterns when using the server's MCP tools.
Loads Postman collection JSON files to provide MCP tools for API interaction, supporting environment variables and multiple authentication methods through four strategic tools for listing, searching, getting details about, and executing API requests.
Ingests and serves Swagger/OpenAPI specifications as MCP tools, providing strategic discovery and interaction with any API endpoint through four tools for listing, searching, getting details, and making API calls.
Swagger/Postman MCP Server
Server that ingests and serves Swagger/OpenAPI specifications and Postman collections as MCP (Model Context Protocol) tools using a simplified strategic approach.
Instead of generating hundreds of individual tools for each API endpoint, this server provides only 4 strategic tools that allow AI agents to dynamically discover and interact with APIs:
Features
Strategic Tool Approach: Only 4 tools instead of hundreds for better AI agent performance
OpenAPI/Swagger Support: Load OpenAPI 2.0/3.0 specifications from URLs or local files
Postman Collection Support: Load Postman collection JSON files from URLs or local files
Environment Variables: Support for Postman environment files
Authentication: Multiple authentication methods (Basic, Bearer, API Key, OAuth2)
Dynamic API Discovery: Tools for listing, searching, and getting details about API endpoints
Request Execution: Execute API requests with proper parameter handling and authentication
Security
This is a personal server!! Do not expose it to the public internet. If the underlying API requires authentication, you should not expose the MCP server to the public internet.
TODO
secrets - the MCP server should be able to use secrets from the user to authenticate requests to the API
Comprehensive test suite
Prerequisites
Node.js (v18 or higher)
Yarn package manager
TypeScript
Installation
Quick Setup for Cursor
Clone and build (commands above)
Configure your
config.json
with your API detailsUpdate paths: Edit
start-mcp.sh
and change thecd
path to your installation directoryAdd to Cursor: Edit
~/.cursor/mcp.json
and add:{ "mcpServers": { "postman-swagger-api": { "command": "/full/path/to/your/swag-mcp/start-mcp.sh" } } }Restart Cursor and start using the 4 strategic MCP tools!
Configuration
The server uses a config.json
file for configuration. You can specify either OpenAPI/Swagger specifications or Postman collections.
OpenAPI/Swagger Configuration
Postman Collection Configuration
Configuration Options
API Configuration
api.type
: Either"openapi"
or"postman"
api.openapi
: OpenAPI/Swagger specific configurationurl
: URL to the OpenAPI specificationapiBaseUrl
: Base URL for API requestsdefaultAuth
: Default authentication configuration
api.postman
: Postman specific configurationcollectionUrl
: URL to the Postman collection (optional)collectionFile
: Path to local Postman collection file (optional)environmentUrl
: URL to the Postman environment (optional)environmentFile
: Path to local Postman environment file (optional)defaultAuth
: Default authentication configuration
Authentication Configuration
type
: Authentication type ("basic"
,"bearer"
,"apiKey"
,"oauth2"
)username
: Username (for basic auth)password
: Password (for basic auth)token
: Token (for bearer/oauth2 auth)apiKey
: API key valueapiKeyName
: API key parameter nameapiKeyIn
: Where to send API key ("header"
or"query"
)
Logging Configuration
log.level
: Logging level ("debug"
,"info"
,"warn"
,"error"
)
Usage
Starting the MCP Server
The server runs via stdio transport for MCP connections:
MCP Integration
This server uses stdio transport and is designed to be used with MCP clients like Claude Desktop or Cursor.
Installing in Cursor
To use this MCP server with Cursor, you need to add it to your Cursor MCP configuration:
1. Locate your Cursor MCP configuration file
The configuration file is located at:
Linux/macOS:
~/.cursor/mcp.json
Windows:
%APPDATA%\.cursor\mcp.json
2. Add the MCP server configuration
Edit your mcp.json
file to include this server:
⚠️ Important: Change the path!
Replace /path/to/your/swag-mcp/start-mcp.sh
with the actual path to your cloned repository. For example:
Linux/macOS:
"/home/username/Documents/swag-mcp/start-mcp.sh"
Windows:
"C:\\Users\\username\\Documents\\swag-mcp\\start-mcp.sh"
3. Example complete configuration
4. Restart Cursor
After saving the configuration file, restart Cursor for the changes to take effect.
5. Verify installation
In Cursor, you should now have access to the 4 strategic MCP tools:
list_requests
- List all available requestsget_request_details
- Get detailed request informationsearch_requests
- Search requests by keywordmake_request
- Execute any API request
Troubleshooting
If the MCP server fails to start:
Update start-mcp.sh path: Edit
start-mcp.sh
and change thecd
path from/path/to/your/swag-mcp
to your actual installation directoryCheck the path: Ensure the path in
mcp.json
points to your actualstart-mcp.sh
fileCheck permissions: Make sure
start-mcp.sh
is executable (chmod +x start-mcp.sh
)Check build: Ensure you've run
npm run build
to compile the TypeScript filesCheck logs: Look in Cursor's MCP logs for error messages
Example Path Updates
If you cloned to /home/username/Documents/swag-mcp/
, then:
In
In
How It Works
Strategic Tool Approach
Instead of generating hundreds of individual tools for each API endpoint, this server provides 4 strategic tools that enable dynamic API discovery and interaction:
OpenAPI/Swagger Mode
4 Strategic Tools:
list_endpoints
- List all available API endpointsget_endpoint_details
- Get detailed information about specific endpointssearch_endpoints
- Search endpoints by keywordmake_api_call
- Execute any API call with proper authentication
Process:
Loads the OpenAPI specification from the configured URL or file
Parses the specification to extract API endpoints, parameters, and security schemes
Makes endpoint information available through the 4 strategic tools
Handles authentication and parameter validation dynamically
Executes API requests and returns responses
Postman Collection Mode
4 Strategic Tools:
list_requests
- List all available requests in the collectionget_request_details
- Get detailed information about specific requestssearch_requests
- Search requests by keywordmake_request
- Execute any request from the collection
Process:
Loads the Postman collection JSON from the configured URL or file
Optionally loads a Postman environment file for variable substitution
Parses requests, folders, and nested items in the collection
Makes request information available through the 4 strategic tools
Handles variable substitution, authentication, and parameter mapping dynamically
Executes requests with proper headers, query parameters, and body data
Benefits of Strategic Tools
Better AI Performance: 4 tools vs hundreds means faster decision making
Dynamic Discovery: AI agents can explore APIs without knowing endpoints beforehand
Flexible Interaction: Any endpoint can be called through
make_api_call
/make_request
Reduced Overwhelm: AI agents aren't flooded with tool options
Strategic Tools Reference
For OpenAPI/Swagger APIs
list_endpoints
Lists all available API endpoints with methods and paths
No parameters required
Returns: Array of endpoint summaries
get_endpoint_details
Get detailed information about a specific endpoint
Parameters:
method
(GET/POST/etc),path
(/users/{id}/etc)Returns: Full endpoint specification with parameters, body schema, responses
search_endpoints
Search endpoints by keyword in path, summary, or description
Parameters:
query
(search term)Returns: Filtered list of matching endpoints
make_api_call
Execute an API call to any endpoint
Parameters:
method
,path
,pathParams
,queryParams
,headers
,body
Returns: API response with status and data
For Postman Collections
list_requests
Lists all available requests in the collection
No parameters required
Returns: Array of request summaries
get_request_details
Get detailed information about a specific request
Parameters:
requestId
orrequestName
Returns: Full request specification
search_requests
Search requests by keyword
Parameters:
query
(search term)Returns: Filtered list of matching requests
make_request
Execute any request from the collection
Parameters:
requestId
,variables
(for substitution)Returns: Request response
Authentication
The server supports multiple authentication methods:
Basic Authentication: Username/password
Bearer Token: JWT or other bearer tokens
API Key: In headers or query parameters
OAuth2: Bearer token based
Authentication can be configured globally or overridden per request.
Example Configuration
Your config.json
should specify either OpenAPI or Postman configuration as shown above.
Example Postman Collection Structure
Development
License
ISC
Environment Variables
PORT
: Server port (default: 3000)API_USERNAME
: Username for API authentication (fallback)API_PASSWORD
: Password for API authentication (fallback)API_TOKEN
: API token for authentication (fallback)DEFAULT_API_BASE_URL
: Default base URL for API endpoints (fallback)DEFAULT_SWAGGER_URL
: Default Swagger specification URL
This server cannot be installed
hybrid server
The server is able to function both locally and remotely, depending on the configuration or use case.
Server that ingests Swagger/OpenAPI specifications and Postman collections, providing just 4 strategic tools that allow AI agents to dynamically discover and interact with APIs instead of generating hundreds of individual tools.
Related MCP Servers
- AsecurityAlicenseAqualityAn MCP server that generates AI agent tools from Postman collections and requests. This server integrates with the Postman API to convert API endpoints into type-safe code that can be used with various AI frameworks.Last updated -13MIT License
- -securityAlicense-qualityThis server facilitates scalable discovery and execution of OpenAPI endpoints using semantic search and high-performance processing, overcoming limitations of large spec handling for streamlined API interactions.Last updated -73MIT License
- -securityAlicense-qualityA server that enables interaction with any API that has a Swagger/OpenAPI specification through Model Context Protocol (MCP), automatically generating tools from API endpoints and supporting multiple authentication methods.Last updated -35104Apache 2.0
- AsecurityFlicenseAqualityA server based on Model Context Protocol that parses Swagger/OpenAPI documents and generates TypeScript types and API client code for different frameworks (Axios, Fetch, React Query).Last updated -121016