Overview

The Postman MCP Server for Newman is a lightweight tool that exposes Postman collection execution as a Model Context Protocol (MCP) tool. It runs Newman (the Postman CLI runner) locally and returns immediate pass/fail test results in a machine-readable JSON format. This makes it easy to integrate Postman-based API tests into automated agents, LLM toolchains, or developer tooling that expects MCP-compatible tool endpoints.

This server is useful when you want programmatic access to API test results without manually running Newman and parsing its console output. By exposing a simple HTTP endpoint, the MCP server accepts collection and environment inputs, runs the collection with Newman, and reports aggregated results (total tests, passed/failed, failure details). It’s particularly handy for local development, debugging, and CI scenarios where a model or automation needs to validate an API quickly and act on pass/fail feedback.

Features

Run Postman collections (file or URL) via Newman and return structured pass/fail results
MCP-compatible API surface for use by LLMs and tool-capable agents
Support for Postman environment files and Newman run options (iterations, globals)
JSON output with summary and detailed failure information for easy automation
Lightweight Node.js server — easy to run locally or inside CI containers
Optional basic authentication / API key support for local security

Installation / Configuration

Prerequisites:

Node.js (14+)
npm or yarn
Newman (installed locally by the server or system-wide)

Clone and install:

git clone https://github.com/shannonlal/mcp-postman.git
cd mcp-postman
npm install

Start the server (development):

# Start with npm
npm start

# Or run with NODE_ENV=production
NODE_ENV=production PORT=8080 npm run start:prod

Environment variables (example .env):

PORT=8080
API_KEY=your_local_api_key_here    # optional: simple auth for endpoints
NEWMAN_BIN=./node_modules/.bin/newman  # optional: custom path to newman

Running Newman manually is not required if the server installs newman as a dependency. If you prefer a global Newman install:

npm install -g newman

Available Resources

The server exposes a small set of HTTP endpoints that are geared toward automation and model integration.

Endpoint summary:

Method	Path	Description
GET	/health	Basic health check (status: ok)
GET	/mcp	MCP discovery / tool metadata (name, description, supported inputs)
POST	/run	Execute a Postman collection and return structured test results

Example: POST /run request body (JSON)

{
  "collection": "https://example.com/collections/my-collection.json",
  "environment": "./envs/staging.postman_environment.json",
  "iterations": 1,
  "globals": null
}

Example successful response:

{
  "summary": {
    "totalTests": 12,
    "failed": 1,
    "passed": 11,
    "durationMs": 1023
  },
  "failures": [
    {
      "itemName": "User login - status 200",
      "assertion": "Status code is 200",
      "responseCode": 500,
      "responseBodySnippet": "Internal Server Error"
    }
  ],
  "rawNewmanSummary": { /* raw newman run summary for diagnostics */ }
}

Use Cases

Automated validation for LLM-driven debugging: An LLM agent can call the MCP /run endpoint to verify an API’s behavior after generating a change, then decide next steps based on pass/fail results.
Local QA and regression checks: Developers can trigger Postman collections programmatically from scripts or local tools and receive structured results for dashboards or reporting.
CI job integration: Use the MCP server in a pipeline step to execute Postman tests and fail the build when test failures are returned. The JSON response can be parsed by pipeline tooling.
Programmatic acceptance tests: Systems that orchestrate multiple services can programmatically validate endpoints by invoking the MCP server and gating deployments on test success.

Tips and Troubleshooting

Collections can be provided as a URL (public or authenticated) or as a file path accessible to the server process.
If you see permission or path errors for Newman, confirm NEWMAN_BIN points to a valid executable or install newman globally.
Use the rawNewmanSummary field in responses for detailed diagnostic info when a test fails.
Protect your local server with API_KEY or local firewall rules if you run it on a shared network.

Repository and source code: https://github.com/shannonlal/mcp-postman

This server is intended as a developer utility to make Postman test results available to tools and agents that understand MCP-style tool interfaces. It’s small, configurable, and designed to integrate smoothly into local dev workflows and automated systems.

Postman MCP Server for Newman Test Results