Postman

What is mcp-postman?

mcp-postman is an MCP (Model Context Protocol) server designed to run Postman collections using Newman. It allows Large Language Models (LLMs) to execute API tests and receive detailed results through a standardized interface, making it easier to integrate API testing into AI-driven workflows.

How to use mcp-postman?

Installation:

• Via Smithery: npx -y @smithery/cli install mcp-postman --client claude
• Manual: Clone the repository, navigate to the directory, install dependencies (pnpm install), and build the project (pnpm build).

Configuration: Add the server to your Claude desktop configuration file (~/Library/Application Support/Claude/claude_desktop_config.json) by specifying the command and arguments to run the built index.js file.

Available Tools:

• run-collection: Runs a Postman collection and returns test results. Parameters include collection (required path/URL), environment (optional path/URL), globals (optional path/URL), and iterationCount (optional number of iterations).

Example Usage in Claude: "Run the Postman collection at /path/to/collection.json and tell me if all tests passed"

Key Features of mcp-postman

• 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, and execution timings.

Use Cases of mcp-postman

• Automated API Testing: Integrate Postman collection execution into CI/CD pipelines or automated testing frameworks.
• LLM-driven API Interaction: Enable LLMs to directly interact with and test APIs, receiving structured feedback on test outcomes.
• Developer Workflows: Streamline the process of running and analyzing Postman tests for developers.

FAQ about mcp-postman

• What is an MCP server? An MCP (Model Context Protocol) server provides a standardized interface for LLMs to interact with external tools and services.
• What is Newman? Newman is a command-line collection runner for Postman.
• Can I use this with other LLMs besides Claude? While the documentation highlights Claude, the underlying MCP server concept is designed for standardized interaction, potentially allowing integration with other LLMs that support the MCP protocol.

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