What is Postman

The MCP (Model Context Protocol) server is an interface for executing Postman collections using the Newman testing framework. It facilitates running API tests programmatically while providing detailed results about the execution status and test outcomes.

Use cases

This server is useful for integrating API testing into workflows that involve large language models (LLMs), enabling automated testing, CI/CD pipelines, and quality assurance processes. It allows users to validate API behaviors and responses systematically.

How to use

Begin by installing the MCP server via Smithery or manually by cloning the repository and building it. Configure the server in the Claude desktop configuration file, specifying the command and arguments for execution. Use the ‘run-collection’ tool to execute a Postman collection by providing necessary parameters, and the server will return detailed test results.

Key features

The server supports running collections with Newman, along with environment and global variable configurations. It provides comprehensive test result summaries, including overall success rates, detailed failure reports, and execution timings.

Where to use

This server can be deployed in environments where API testing is critical, such as software development, integration testing, and automated testing frameworks, particularly when working with LLMs that require reliable API validation.

Postman MCP Server

An MCP (Model Context Protocol) server that enables running Postman collections using Newman. This server allows LLMs to execute API tests and get detailed results through a standardized interface.

Features

• Run Postman collections using Newman
• Support for environment files
• Support for global variables
• Detailed test results including:
  • Overall success/failure status
  • Test summary (total, passed, failed)
  • Detailed failure information
  • Execution timings

Installation

Installing via Smithery

To install Postman Runner for Claude Desktop automatically via Smithery:

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

Manual Installation

# Clone the repository
git clone <repository-url>
cd mcp-postman

# Install dependencies
pnpm install

# Build the project
pnpm build

Usage

Configuration

Add the server to your Claude desktop configuration file at ~/Library/Application Support/Claude/claude_desktop_config.json:

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

Available Tools

run-collection

Runs a Postman collection and returns the test results.

Parameters:

• collection (required): Path or URL to the Postman collection
• environment (optional): Path or URL to environment file
• globals (optional): Path or URL to globals file
• iterationCount (optional): Number of iterations to run

Example Response:

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

Example Usage in Claude

You can use the server in Claude by asking it to run a Postman collection:

“Run the Postman collection at /path/to/collection.json and tell me if all tests passed”

Claude will:

1. Use the run-collection tool
2. Analyze the test results
3. Provide a human-friendly summary of the execution

Development

Project Structure

src/
  ├── index.ts           # Entry point
  ├── server/
  │   ├── server.ts     # MCP Server implementation
  │   └── types.ts      # Type definitions
  └── newman/
      └── runner.ts     # Newman runner implementation
test/
  ├── server.test.ts    # Server tests
  ├── newman-runner.test.ts  # Runner tests
  └── fixtures/         # Test fixtures
      └── sample-collection.json

Running Tests

# Run tests
pnpm test

# Run tests with coverage
pnpm test:coverage

Building

# Build the project
pnpm build

# Clean build artifacts
pnpm clean

Contributing

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

ISC