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:

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)

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

# Clone the repository
git clone <repository-url>
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

Quick Setup for Cursor

Clone and build (commands above)
Configure your config.json with your API details
Update paths: Edit start-mcp.sh and change the cd path to your installation directory

Add 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

{
  "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"
  }
}

Postman Collection Configuration

{
  "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"
  }
}

Configuration Options

API Configuration

api.type: Either "openapi" or "postman"
api.openapi: OpenAPI/Swagger specific configuration
- url: URL to the OpenAPI specification
- apiBaseUrl: Base URL for API requests
- defaultAuth: Default authentication configuration
api.postman: Postman specific configuration
- collectionUrl: 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 value
apiKeyName: API key parameter name
apiKeyIn: 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:

# 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:simple

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:

{
  "mcpServers": {
    "postman-swagger-api": {
      "command": "/path/to/your/swag-mcp/start-mcp.sh"
    }
  }
}

⚠️ 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

{
  "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. 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 requests
get_request_details - Get detailed request information
search_requests - Search requests by keyword
make_request - Execute any API request

Troubleshooting

If the MCP server fails to start:

Update start-mcp.sh path: Edit start-mcp.sh and change the cd path from /path/to/your/swag-mcp to your actual installation directory
Check the path: Ensure the path in mcp.json points to your actual start-mcp.sh file
Check 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 files
Check logs: Look in Cursor's MCP logs for error messages

Example Path Updates

If you cloned to /home/username/Documents/swag-mcp/, then:

In start-mcp.sh:

cd "/home/username/Documents/swag-mcp"

In ~/.cursor/mcp.json:

"command": "/home/username/Documents/swag-mcp/start-mcp.sh"

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 endpoints
get_endpoint_details - Get detailed information about specific endpoints
search_endpoints - Search endpoints by keyword
make_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 collection
get_request_details - Get detailed information about specific requests
search_requests - Search requests by keyword
make_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 or requestName
- 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

{
  "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"]
        }
      }
    }
  ]
}

Development

# Install dependencies
npm install

# Run in development mode
npm run dev

# Run tests
npm test

# Build for production
npm run build

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

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:

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)

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

# Clone the repository
git clone <repository-url>
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

Quick Setup for Cursor

Clone and build (commands above)
Configure your config.json with your API details
Update paths: Edit start-mcp.sh and change the cd path to your installation directory

Add 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

{
  "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"
  }
}

Postman Collection Configuration

{
  "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"
  }
}

Configuration Options

API Configuration

api.type: Either "openapi" or "postman"
api.openapi: OpenAPI/Swagger specific configuration
- url: URL to the OpenAPI specification
- apiBaseUrl: Base URL for API requests
- defaultAuth: Default authentication configuration
api.postman: Postman specific configuration
- collectionUrl: 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 value
apiKeyName: API key parameter name
apiKeyIn: 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:

# 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:simple

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:

{
  "mcpServers": {
    "postman-swagger-api": {
      "command": "/path/to/your/swag-mcp/start-mcp.sh"
    }
  }
}

⚠️ 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

{
  "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. 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 requests
get_request_details - Get detailed request information
search_requests - Search requests by keyword
make_request - Execute any API request

Troubleshooting

If the MCP server fails to start:

Update start-mcp.sh path: Edit start-mcp.sh and change the cd path from /path/to/your/swag-mcp to your actual installation directory
Check the path: Ensure the path in mcp.json points to your actual start-mcp.sh file
Check 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 files
Check logs: Look in Cursor's MCP logs for error messages

Example Path Updates

If you cloned to /home/username/Documents/swag-mcp/, then:

In start-mcp.sh:

cd "/home/username/Documents/swag-mcp"

In ~/.cursor/mcp.json:

"command": "/home/username/Documents/swag-mcp/start-mcp.sh"

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 endpoints
get_endpoint_details - Get detailed information about specific endpoints
search_endpoints - Search endpoints by keyword
make_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 collection
get_request_details - Get detailed information about specific requests
search_requests - Search requests by keyword
make_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 or requestName
- 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

{
  "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"]
        }
      }
    }
  ]
}

Development

# Install dependencies
npm install

# Run in development mode
npm run dev

# Run tests
npm test

# Build for production
npm run build

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