MCP Postman

🚀 MCP Postman Server

A server based on the Model Context Protocol (MCP) that supports running Postman collections using Newman. This server allows Large Language Models (LLMs) to execute API tests and obtain detailed test results through a standardized interface.

🚀 Quick Start

This MCP-based server enables LLMs to perform API tests using Newman for Postman collections and retrieve detailed test results.

✨ Features

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

📦 Installation

Install via Smithery

Automatically install Postman Runner for Claude Desktop through 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

Server Configuration

Add the 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 test results.

Parameters:

• collection (required): Path or URL of the Postman collection.
• environment (optional): Path or URL of the environment file.
• globals (optional): Path or URL of 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 run a Postman collection in Claude as follows: "Run the Postman collection located 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 friendly execution summary.

📚 Documentation

Project Structure

• src/: Contains the main implementation logic of the server.
• build/: Files generated by the build process.
• package.json: Manages project dependencies and build scripts.
• README.md: Project documentation and usage instructions.

Contribution Guidelines

1. Clone the Repository: First, clone this repository to your local development environment.

   git clone <repository-url>
   cd mcp-postman
   

2. Install Dependencies: Install the project dependencies using npm or pnpm.

   pnpm install
   

3. Start in Development Mode: You can start the development server using the following command.

   pnpm dev
   

4. Build the Project: In a production environment, you can use the following command to build.

   pnpm build
   

5. Testing: Run the test suite to ensure the correctness of the code.

   pnpm test
   

Important Note

• Ensure you have the latest versions of Node.js and npm or pnpm installed to avoid compatibility issues.
• Use the built files (located in the build/ directory) in a production environment, not the development mode files.
• Follow the project contribution guidelines and code style guide to ensure code consistency and maintainability.

📄 License

This project is licensed under the MIT License.

By following the above steps, you can easily integrate Postman collections into your development workflow and leverage the powerful features of the MCP server to automate and manage API tests.