MCP Postman

🚀 Postman MCP Server

A server based on the Model Context Protocol (MCP) that runs Postman collections via Newman. This server enables Large Language Models (LLMs) to execute API tests and obtain detailed test results through a unified interface.

🚀 Quick Start

This is a server based on the Model Context Protocol (MCP), which uses Newman to run Postman collections. It allows Large Language Models (LLMs) to perform API tests and obtain detailed test results through a unified interface.

✨ Features

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

📦 Installation

Install via Smithery

To automatically install the Postman runner 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 Examples

Configuration

Add this server to your Claude desktop configuration file ~/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

Run a Postman collection and return the test results.

Parameters:

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

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 have Claude run a Postman collection like this: "Run the Postman collection located at /path/to/collection.json and tell me if all tests passed."

Claude will:

1. Call the run-collection tool using the MCP protocol.
2. Receive detailed test results.
3. Generate a natural - language test report.

🔧 Technical Details

Project Structure

- src/
  - CollectionRunner.ts # Main class for handling Postman collection runs
  - NewmanAdapter.ts     # Adapter interface for Newman
  - types.ts            # Define MCP protocol types

Run Tests

npm test

# Or test a specific file
npm test src/CollectionRunner.spec.ts

Build the Project

pnpm build

🤝 Contribution Guidelines

1. Fork this repository.
2. Create a new feature branch: git checkout -b feature/NewmanAdapter.
3. Commit your changes: git commit -m 'feat: Add Newman support'.
4. Push to the remote: git push origin feature/NewmanAdapter.
5. Create a Pull Request.

📄 License

MIT