Execute Postman API Tests with LLMs
MCP server that runs Postman collections via Newman and returns detailed test results, so an LLM can execute API tests conversationally.
Why it matters
Enable Large Language Models to execute Postman API tests via a standardized interface. This asset allows LLMs to run collections, analyze results, and provide detailed feedback for API testing.
Outcomes
What it gets done
Run Postman collections using Newman.
Support environment and global variable files.
Provide detailed test results, including success/failure status and error information.
Include execution timing characteristics for performance analysis.
Install
Add it to your toolbox
Run in your project directory:
curl -fsSL https://spark.entire.vc/get/vb-postman | bash Capabilities
Tools your agent gets
Runs a Postman collection and returns test results, including overall success/failure status and detailed execution information.
Overview
Postman MCP Server
An MCP server that runs Postman collections via Newman and returns structured pass/fail test results, failure details, and timings. Use when an assistant needs to execute an existing Postman API test collection and summarize the results conversationally.
What it does
Postman MCP Server lets an LLM run Postman collections through Newman (Postman's CLI collection runner) and get back structured test results, rather than the developer running Newman manually and parsing its output themselves. It exposes one tool, run-collection, which executes a collection with optional environment and global-variable files and returns overall success/failure status, a pass/fail/total test summary, detailed failure information, and execution timings.
When to use - and when NOT to
Use this connector when you want an assistant to run an API test suite and report results conversationally - for example, asking Claude "Run the Postman collection at /path/to/collection.json and tell me if all tests passed" and having it execute the tool, interpret the JSON result, and summarize it in plain language. It is a test-execution tool, not a collection editor: it runs an existing Postman collection file or URL rather than helping author or modify the collection's requests.
Capabilities
run-collection takes a required collection (path or URL to the Postman collection), an optional environment (path or URL to an environment file), an optional globals (path or URL to a globals file), and an optional iterationCount for repeated runs. The response includes a success boolean, a summary with total/passed/failed counts, a failures array with details on anything that failed, and timings with started/completed/duration fields.
{
"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 }
}
How to install
npx -y @smithery/cli install mcp-postman --client claude
for automatic Smithery install, or manually: clone the repository, run pnpm install, then pnpm build. Configure it in Claude Desktop's claude_desktop_config.json as a command-type server pointing node at the built build/index.js with its absolute path.
Who it's for
Developers and QA engineers who want an AI assistant to run existing Postman API test collections and summarize pass/fail results in plain language - useful for quick regression checks or verifying an environment's API behavior without manually invoking Newman and reading raw JSON output. The project itself ships a standard TypeScript test/build setup (pnpm test, pnpm test:coverage, pnpm build) for anyone extending the Newman runner or MCP server implementation. The project structure separates the MCP server implementation (src/server/) from the Newman execution logic (src/newman/runner.ts), which keeps the collection-running logic testable independently of the MCP transport layer around it. Sample fixtures under test/fixtures/ (including a sample collection) give contributors a ready-made collection to exercise the runner against without needing a live API to test, and the project's dedicated server.test.ts and newman-runner.test.ts suites cover the MCP protocol layer and the Newman execution path separately.
Source README
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 collectionenvironment(optional): Path or URL to environment fileglobals(optional): Path or URL to globals fileiterationCount(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:
- Use the run-collection tool
- Analyze the test results
- 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
FAQ
Common questions
Discussion
Questions & comments · 0
Sign In Sign in to leave a comment.