Metadata-Version: 2.4
Name: postman-runner-mcp
Version: 1.0.0
Summary: A generic MCP server for executing Postman collections — supports v2.1 collections, environments, variable chaining, and scripting
Project-URL: Homepage, https://github.com/PGNextGen/postman-runner-mcp
Project-URL: Repository, https://github.com/PGNextGen/postman-runner-mcp
Project-URL: Issues, https://github.com/PGNextGen/postman-runner-mcp/issues
Author-email: Piyush Gupta <pgengineered@gmail.com>
License-Expression: MIT
Keywords: api-testing,collection-runner,mcp,postman
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Testing
Requires-Python: >=3.10
Requires-Dist: mcp[cli]
Provides-Extra: all
Requires-Dist: dukpy>=0.4.0; extra == 'all'
Provides-Extra: js
Requires-Dist: dukpy>=0.4.0; extra == 'js'
Description-Content-Type: text/markdown

# Postman Runner MCP

A full-featured [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) 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

```bash
# 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`):

```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

```bash
# 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
