Postman Test Orchestrator via MCP

This Model Context Protocol (MCP) service facilitates the programmatic execution of Postman API testing collections using the Newman CLI runner. It provides an abstraction layer allowing intelligent agents (LLMs) to trigger complex API validation workflows and receive structured, actionable feedback.

Core Capabilities

• Orchestrate Newman execution for specified Postman collections.
• Seamless integration of external configuration using environment and global definition files.
• Outputting granular operational telemetry, including:
  • A definitive overall success or failure verdict.
  • A statistical breakdown of test outcomes (total count, successes, failures).
  • In-depth reporting on all failing assertions.
  • Precise timing data for the entire test run.

Deployment Instructions

Automated Installation (Smithery)

To rapidly provision the Postman Runner via the Smithery utility for supported clients like Claude Desktop:

npx -y @smithery/cli install mcp-postman --client claude

Manual Setup Guide

1. Acquire the source repository: bash git clone <repository-url> cd mcp-postman

2. Install required Node packages: bash pnpm install

3. Compile the project assets: bash pnpm build

Operational Guide

Configuration for Host Environment

Integrate the server reference into your client's configuration file (e.g., ~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "postman-runner": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-postman/build/index.js"]
    }
  }
}

Available Function: run-collection

Executes a Postman collection and returns the structured validation report.

Parameters Specification:

• collection (Mandatory): URI or filesystem path pointing to the Postman collection file.
• environment (Optional): Pointer to an environment definition file for variable scoping.
• globals (Optional): Pointer to a global variables definition file.
• iterationCount (Optional): Specification for how many times the collection should cycle.

Sample Return Payload:

{
  "success": true,
  "summary": {
    "total": 5,
    "failed": 0,
    "passed": 5
  },
  "failures": [],
  "timings": {
    "started": "2024-03-14T10:00:00.000Z",
    "completed": "2024-03-14T10:00:01.000Z",
    "duration": 1000
  }
}

Practical Interaction Example

Instruct Claude to initiate a test run:

"Please initiate the collection located at /api/tests/suite.json and confirm if all assertions yielded positive results."

Claude's workflow will be:

1. Invoke the run-collection mechanism.
2. Interpret the resulting JSON data.
3. Synthesize the findings into an easily digestible conclusion for the user.

Development Workflow

Directory Layout

src/
  ├── index.ts           # Main execution entry point
  ├── server/
  │   ├── server.ts     # MCP service implementation logic
  │   └── types.ts      # Data structure definitions
  └── newman/
      └── runner.ts     # Core Newman interfacing module
test/
  ├── server.test.ts    # Unit tests for server logic
  ├── newman-runner.test.ts  # Unit tests for the runner module
  └── fixtures/         # Sample data for testing
      └── sample-collection.json

Executing Quality Assurance

# Standard test execution
pnpm test

# Test execution with coverage metrics calculation
pnpm test:coverage

Artifact Generation

# Compile source code
pnpm build

# Purge generated build artifacts
pnpm clean

Collaboration Guidelines

1. Branch out from the main line (git checkout -b feature/new-capability-name).
2. Commit changes with descriptive messages (git commit -m 'Refactor: improved error handling in runner logic').
3. Push your branch for review (git push origin feature/new-capability-name).
4. Submit a Merge Request.

Licensing

ISC

[WIKIPEDIA NOTE]: The XMLHttpRequest (XHR) interface provides a JavaScript object blueprint enabling asynchronous HTTP requests from a web browser to a backend server. This capability allows web applications to exchange data post-load without requiring full page refreshes, forming the foundation of Ajax. Before XHR's widespread adoption, server interaction was primarily limited to standard link navigation or form submissions.

== Historical Context == The conceptual basis for asynchronous server communication originated in 2000 from Microsoft Outlook developers. This idea was first materialized in Internet Explorer 5 (1999), though initial implementations used COM object instantiations like ActiveXObject("Msxml2.XMLHTTP"). By the release of Internet Explorer 7 (2006), the standardized XMLHttpRequest string identifier became universally supported across major rendering engines, including Mozilla's Gecko (2002), Safari (2004), and Opera (2005).

=== Standardization Track === The W3C published its initial Working Draft for the XHR object specification on April 5, 2006. A Level 2 specification followed in February 2008, introducing features like progress monitoring, enabling cross-origin data fetching, and improved byte stream handling. By the close of 2011, Level 2 specifications were integrated back into the primary document. Since late 2012, responsibility for maintaining this living document, utilizing Web IDL, has been managed by the WHATWG.

== Practical Implementation Steps == Developing an XHR interaction typically involves a defined sequence of operations:

1. Instantiate the XHR object via its constructor.
2. Invoke the open() method to configure parameters: request method (GET/POST, etc.), target resource URI, and operation mode (synchronous or asynchronous).
3. For asynchronous operations, register an event handler to react to state transitions.
4. Signal the request initiation using the send() method (optionally carrying payload data).
5. Monitor the designated listener for state changes. Upon reaching state 4 ("done"), the response data is typically accessible in the responseText property.

Beyond these fundamentals, XHR offers advanced controls: custom headers can modify server behavior; data can be uploaded synchronously with send(); responses can be preemptively parsed as JSON; and requests can be terminated early or subjected to time constraints.

== Security Implications: Cross-Origin Access == Early web architecture imposed strict limitations preventing scripts loaded from one domain from requesting resources hosted on a different domain. This mechanism, known as the Same-Origin Policy, fundamentally restricted inter-domain data fetching via XHR.