postman-runner-mcp 1.0.0

A generic MCP server for executing Postman collections — supports v2.1 collections, environments, variable chaining, and scripting

Postman Runner MCP

A full-featured Model Context Protocol (MCP) server for executing Postman collections using Python. Enables AI assistants to run, inspect, and manage API test workflows from any Postman v2.1 collection file — with a strict, safe execution pipeline that never guesses credentials.

What Can This MCP Do?

Core Capabilities

Capability	Description
Execute Postman Collections	Run any .postman_collection.json end-to-end with full variable resolution
Strict Safety Pipeline	Validates → Scans variables → Generates config → Validates user input → Executes. Never runs without required credentials.
Pre-flight Analysis	Scans collections to identify exactly what variables the user must provide vs. what's auto-resolved by scripts
OAuth2 Auto-Token	Automatically fetches and refreshes OAuth2 tokens (Client Credentials & Password grant)
Variable Chaining	Extracts and chains variables between requests via pre-request and test scripts
Data-Driven Testing	Run collections multiple times with different data sets from CSV or JSON files
Parallel Execution	Execute independent requests concurrently using thread pools
Retry with Backoff	Configurable retry logic with exponential backoff for transient failures (429, 5xx)
Code Generation	Generate cURL commands or Python requests code from any collection request
Report Export	Export results as JSON, JUnit XML, or HTML reports
Dry Run Mode	Preview resolved URLs without making HTTP calls
Real JS Execution	Optional V8-based JavaScript engine for full script support (via dukpy)

Authentication Support

Auth Type	How It Works
Bearer Token	Resolves {{token}} from variables
Basic Auth	Base64-encodes username:password from variables
API Key	Injects key into header or query param
OAuth2 (Client Credentials)	Auto-fetches token from token endpoint before execution
OAuth2 (Password Grant)	Auto-fetches token with username/password

Script Interpretation

• Pattern-based interpreter (default): Handles common pm.environment.set(), response JSON parsing, regex extraction
• Full JS engine (optional): Install dukpy for complete JavaScript execution with full Postman sandbox API support

MCP Tools

Tool	Description
prepare_collection	Validates collection + scans variables + generates config file for user to fill
run_collection	Executes a collection after validating all requirements are met
inspect_collection	View collection metadata, folders, and request listing
dry_run_collection	Preview resolved URLs without making HTTP calls
check_status	Check if a collection is ready to execute (config filled?)
list_collections	Scan a directory for available collection files

Execution Pipeline

┌──────────────┐     ┌──────────────┐     ┌──────────────────┐
│ 1. VALIDATE  │ ──▶ │ 2. SCAN VARS │ ──▶ │ 3. GENERATE      │
│   collection │     │   & analyze  │     │   config file    │
└──────────────┘     └──────────────┘     └───────┬──────────┘
                                                  │
                                        (user fills config)
                                                  │
┌──────────────┐     ┌──────────────┐     ┌──────▼──────────┐
│ 5. EXECUTE   │ ◀── │ 4. VALIDATE  │ ◀── │   user provides │
│   collection │     │   user config│     │   variables     │
└──────────────┘     └──────────────┘     └─────────────────┘

The server never guesses variable values — it always asks the user.

Architecture

postman-runner-mcp/
├── pyproject.toml                 # Project metadata & dependencies
├── server.py                      # Entry point
└── src/
    └── postman_runner_mcp/
        ├── server.py              # MCP tool definitions (6 tools)
        ├── orchestrator.py        # Strict pipeline orchestrator
        ├── runner/
        │   ├── engine.py          # Core execution engine
        │   ├── models.py          # Data models (RequestResult, RunSummary)
        │   ├── variables.py       # Variable store with scoped resolution
        │   ├── scripts.py         # Regex-based script interpreter
        │   ├── js_engine.py       # Full V8 JavaScript engine (optional)
        │   ├── auth.py            # Authentication handler (Bearer/Basic/API Key/OAuth2)
        │   ├── oauth2.py          # OAuth2 auto-token acquisition & refresh
        │   ├── preflight.py       # Pre-flight variable analyzer
        │   ├── retry.py           # Retry with exponential backoff
        │   ├── parallel.py        # Concurrent request execution
        │   └── data_driven.py     # CSV/JSON iteration data support
        ├── parsers/
        │   ├── collection.py      # Collection validator & parser
        │   └── environment.py     # Environment file parser
        ├── generators/
        │   ├── curl_generator.py  # cURL command generation
        │   └── python_generator.py # Python requests code generation
        ├── exporters/
        │   ├── json_exporter.py   # JSON report export
        │   ├── junit_exporter.py  # JUnit XML report export
        │   └── html_exporter.py   # HTML report export
        └── utils/
            ├── formatting.py      # Output formatting
            ├── validator.py       # Collection structure validator
            └── diff.py            # Diff utilities

Installation

# No install needed if using uvx (recommended for MCP):
uvx postman-runner-mcp

# Or install globally with pip:
pip install postman-runner-mcp

# With optional JS engine support:
pip install "postman-runner-mcp[js]"

Configuration

Add to your MCP config file (e.g. mcp.json, .kiro/settings/mcp.json, or ~/.kiro/settings/mcp.json):

{
  "mcpServers": {
    "postman-runner": {
      "command": "uvx",
      "args": ["postman-runner-mcp"],
      "disabled": false,
      "autoApprove": []
    }
  }
}

Usage Examples

1. Prepare a Collection (Recommended First Step)

"Prepare the collection at /path/to/my_api.json"

This validates the collection, scans all variables, and generates a config file listing exactly what you need to provide.

2. Run a Collection

"Run the collection at /path/to/my_api.json with config /path/to/config.json"

3. Run with Inline Variables

"Run /path/to/collection.json with variables: {"base_url": "https://api.staging.com", "api_key": "my-key"}"

4. Run a Specific Folder

"Run only the Authentication folder from /path/to/collection.json"

5. Preview Without Executing

"Dry run the collection at /path/to/collection.json"

6. Inspect Collection Structure

"Show me the structure of /path/to/collection.json with all requests listed"

7. Check Readiness

"Check if /path/to/collection.json is ready to run"

Supported Postman Features

Feature	Status
Postman Collection v2.1	✅
Postman Collection v2.0	✅
Variable substitution ({{var}})	✅
Environment variables	✅
Collection variables	✅
OS environment variables ($env.VAR)	✅
Dynamic variables ($randomUUID, $timestamp)	✅
Pre-request scripts	✅
Test scripts (variable extraction)	✅
Full JavaScript execution (optional)	✅ (with dukpy)
Bearer Token auth	✅
Basic Auth	✅
API Key auth (header/query)	✅
OAuth2 — Client Credentials	✅
OAuth2 — Password Grant	✅
OAuth2 — Auto-refresh on expiry	✅
URL-encoded body	✅
Raw JSON body	✅
Form data (text fields)	✅
GraphQL body	✅
Path variables (:id)	✅
Folder filtering	✅
Request chaining	✅
Data-driven iterations (CSV/JSON)	✅
Parallel request execution	✅
Retry with exponential backoff	✅
Stop on first error	✅
Request delay (throttling)	✅
cURL command generation	✅
Python code generation	✅
JUnit XML export	✅
HTML report export	✅
JSON report export	✅
Location header extraction	✅
File uploads	❌ (text fields only)
Cookie management	❌
WebSocket / gRPC	❌

Security

• No hardcoded secrets — all credentials are loaded from user-provided config files or environment variables
• Strict pipeline — the server blocks execution until all required variables are explicitly provided
• Sensitive masking — environment inspector masks values marked as secrets
• SSL configurable — SSL verification can be enabled/disabled per execution
• The .postman-runner/ directory (auto-generated configs) should be added to .gitignore

Development

# Run directly
uv run postman-runner-mcp

# Run with MCP Inspector for debugging
npx @modelcontextprotocol/inspector uv --directory . run postman-runner-mcp

# Run with full JS engine support
uv pip install -e ".[js]"
uv run postman-runner-mcp

Requirements

• Python 3.10+
• mcp[cli] package (FastMCP framework)
• No additional dependencies for core features (uses stdlib http.client)
• Optional: dukpy for full JavaScript execution engine

License

MIT