newman-ai-mcp
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@newman-ai-mcp run my collection and summarize the failing tests"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Local MCP server over stdio for automated Postman/Newman QA. It exposes nine tools: six deterministic tools and three AI-powered tools. AI can run locally with Qwen3.5-2B through node-llama-cpp, or through an OpenAI-compatible API.
Requirements
Node.js 20 or newer.
npm.
For the default local AI provider: enough disk space and memory for the Qwen3.5-2B model. The model is downloaded separately.
Or an OpenAI-compatible endpoint and API key.
Related MCP server: Code2Postman MCP
Install from this repository
Clone the repository, install dependencies, and build the TypeScript source:
git clone https://github.com/ItsJJStack/newman-ai-mcp.git
cd newman-ai-mcp
npm ci
npm run buildThe built server is dist/index.js. Start it directly with:
node dist/index.jsTo run the test suite:
npm testInstall from npm
After the package is published, install it in a project:
npm install newman-ai-mcpOr run a CLI command without installing it globally:
npx newman-ai-mcp --help
npx newman-ai-mcp --check-llmThe package exposes the newman-ai-mcp executable. For MCP clients, configure the executable using the examples below. These npm commands describe the intended published-package workflow; they require the package to be available in the npm registry.
Configure the AI provider
The local provider is the default. Download and verify its model once:
npx newman-ai-mcp --download
npx newman-ai-mcp --check-llmFor a source checkout, use node dist/index.js instead of npx newman-ai-mcp.
To use an OpenAI-compatible provider, set these environment variables:
Variable | Purpose |
| Set to |
| API base URL, for example |
| API key. Keep it in the environment or a secret manager; do not put it in source control. |
| Model name accepted by the endpoint. |
For Postman collection UIDs, set POSTMAN_API_KEY in the server environment. Never put API keys in URLs.
Configure an MCP client
The server uses stdio. Set command and args to the executable and arguments supported by your MCP client. Use the absolute path to dist/index.js for a repository checkout. After npm publication, npx can run the package executable.
Repository checkout with the local provider
Replace /absolute/path/to/newman-ai-mcp with the cloned repository path:
{
"mcpServers": {
"newman-ai-mcp": {
"command": "node",
"args": ["/absolute/path/to/newman-ai-mcp/dist/index.js"],
"env": {
"NEWMAN_MCP_LLM_PROVIDER": "local"
}
}
}
}Published npm package with an OpenAI-compatible provider
Configure your MCP client to run the package with npx. Provide the API key through the client environment, not in the JSON committed to your project:
{
"mcpServers": {
"newman-ai-mcp": {
"command": "npx",
"args": ["--yes", "newman-ai-mcp"],
"env": {
"NEWMAN_MCP_LLM_PROVIDER": "openai-compatible",
"NEWMAN_MCP_LLM_BASE_URL": "https://api.openai.com/v1",
"NEWMAN_MCP_LLM_MODEL": "gpt-4o-mini"
}
}
}
}Set NEWMAN_MCP_LLM_API_KEY securely in the MCP client's environment. NEWMAN_MCP_ROOT controls the allowed root for local file reads and writes; by default, it is the server's current working directory. Use absolute paths for collection, environment, iteration-data, and output files under that root.
Using the tools
The examples below show the JSON arguments to pass to each MCP tool. Replace sample paths with files under NEWMAN_MCP_ROOT. AI tools use the configured provider. Use collectionSource as a local path, an HTTPS URL, or a Postman collection UID.
1. generate_tests_from_story
Generate tests from a story. A story must contain at least 20 characters.
{
"collectionSource": "./fixtures/collection.json",
"userStory": "As a registered user, I can sign in with valid credentials and receive an access token.",
"acceptanceCriteria": [
"Valid credentials return status 200 and an access token.",
"Invalid credentials return status 401."
],
"maxTestCases": 2,
"outputPath": "./output/login-tests.postman_collection.json"
}2. generate_test_dataset
Create iteration data for variables used by a collection or a selected item:
{
"collectionSource": "./fixtures/collection.json",
"targetItemName": "Create user",
"scenarioCount": 5,
"outputPath": "./output/create-user-data.json"
}3. analyze_newman_failure
Pass a failure returned by run_newman_collection or generate_newman_report to get a diagnosis:
{
"collectionSource": "./fixtures/collection.json",
"failure": {
"itemName": "Login",
"itemPath": ["Auth"],
"iteration": 0,
"type": "assertion",
"errorMessage": "expected 401 to equal 200",
"responseCode": 401
}
}4. run_newman_collection
Run a collection with an environment file and inline variables:
{
"collectionSource": "./fixtures/collection.json",
"environmentPath": "./fixtures/environment.json",
"envVars": {
"baseUrl": "http://127.0.0.1:3000"
},
"iterationCount": 1,
"executionControl": {
"timeout": 300000,
"bail": true
}
}5. generate_newman_report
Run a collection and write JSON and JUnit reports to an output directory:
{
"collectionSource": "./fixtures/collection.json",
"environmentPath": "./fixtures/environment.json",
"reportFormats": ["json", "junit"],
"outputDir": "./output/reports",
"insecure": false
}6. inspect_postman_collection
Inspect the collection structure without running requests:
{
"collectionSource": "./fixtures/collection.json",
"folder": "Auth",
"maxItems": 50
}7. validate_postman_collection
Statically validate a collection and optionally provide environment and iteration data:
{
"collectionSource": "./fixtures/collection.json",
"environmentPath": "./fixtures/environment.json",
"iterationDataPath": "./fixtures/iteration-data.csv"
}8. generate_cicd_pipeline
Generate CI/CD configuration. Omitting outputPath returns the configuration without writing a file:
{
"platform": "github-actions",
"collectionSource": "./fixtures/collection.json",
"environmentPath": "./fixtures/environment.json",
"outputPath": "./output/.github/workflows/api-tests.yml"
}The default is not to overwrite an existing file. Pass "overwrite": true only when replacement is intended.
9. import_openapi_spec
Create a Postman collection from a local OpenAPI or Swagger file:
{
"specSource": "./fixtures/openapi.yaml",
"outputPath": "./output/api.postman_collection.json",
"mode": "create",
"folderStrategy": "Tags",
"generateBasicTests": true
}To sync, also pass "mode": "sync" and "collectionSource": "./output/api.postman_collection.json". The source collection is read-only; write the result to a different outputPath. Existing files are not overwritten unless "overwrite": true is supplied.
File access and secrets
Local paths are restricted to NEWMAN_MCP_ROOT. Remote collection and specification sources must use HTTPS. For a Postman UID, set POSTMAN_API_KEY in the process environment. For an OpenAI-compatible provider, set NEWMAN_MCP_LLM_API_KEY in the process environment or secret manager. Do not commit API keys or place them in URL query strings.
Development
npm ci
npm run build
npm testLicense
This project is licensed under the Apache License 2.0. See LICENSE. Third-party dependencies and model files retain their own licenses.
Available Tools
9 toolsanalyze_newman_failureAnalyze Newman failureBRead-only
Diagnoses a failure and suggests a corrected script or request.
Inputs: failure (required), collectionSource (required). Returns: llm, category, fixTarget, fixedExec, +4 more
generate_cicd_pipelineGenerate CI/CD pipelineA
Generates configuration to run Newman in CI/CD or Docker (GitHub Actions, GitLab CI, Azure DevOps, Jenkins, Dockerfile).
Inputs: platform (required), collectionSource (required), overwrite, outputPath, +4 more. Returns: content, platform, writtenTo, suggestedPath, +1 more
generate_newman_reportGenerate Newman reportA
Runs a collection and generates a report for auditing or CI/CD (JSON, JUnit, HTML Extra).
Inputs: outputDir (required), reportFormats (required), collectionSource (required), insecure, +2 more. Returns: stats, aborted, reports, success, +5 more
generate_test_datasetGenerate test datasetB
Generates a --iteration-data file (.json or .csv) with positive, negative, and boundary-value cases.
Inputs: outputPath (required), collectionSource (required), overwrite, scenarioCount, +1 more. Returns: rows, format, columns, outputPath
generate_tests_from_storyGenerate tests from storyC
Generates API test cases from a user story or natural-language idea for a Postman collection (path, URL, or UID).
Inputs: userStory (required), collectionSource (required), overwrite, outputPath, +4 more. Returns: llm, status, retries, skipped, +9 more
import_openapi_specImport OpenAPI specificationA
Generates a Postman v2.1 collection from OpenAPI 3.0/3.1/Swagger 2.0 (JSON/YAML), or syncs an existing collection with a new spec version. Deterministic: uses openapi-to-postmanv2 without a model.
Inputs: outputPath (required), specSource (required), mode, overwrite, +7 more. Returns: mode, spec, sync, folders, +6 more
inspect_postman_collectionInspect Postman collectionARead-only
Returns a lightweight map of the collection without running it, so the agent can see what exists before calling other tools.
Inputs: collectionSource (required), folder, maxItems. Returns: name, items, folders, truncated, +4 more
run_newman_collectionRun Newman collectionB
Runs a local or remote collection with full control over variables, timeouts, SSL, iterations, and state export.
Inputs: collectionSource (required), folder, envVars, exports, +7 more. Returns: stats, aborted, success, timings, +4 more
validate_postman_collectionValidate Postman collectionARead-only
Instant static validation (no model or HTTP requests). Checks JSON, schema, script syntax, forbidden APIs, and undefined variables.
Inputs: collectionSource (required), globalsPath, environmentPath, iterationDataPath. Returns: valid, issues, summary
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 9 tools
Most tools target distinct lifecycle stages (inspect, validate, import, generate tests, run, report, CI/CD, dataset, diagnose). The main overlap is run_newman_collection vs generate_newman_report, which both execute a collection; the descriptions distinguish them (control vs. report artifact), but an agent could still hesitate. inspect vs validate is also close but clarified as map-only vs static checks.
All nine tools follow a consistent snake_case verb_noun pattern (run_*, generate_*, inspect_*, validate_*, import_*, analyze_*). Naming is predictable and self-describing across the whole surface.
Nine tools is well within the ideal 3-15 range for a Postman/Newman workflow server. Each tool covers a distinct phase (author, validate, import, run, report, CI/CD, diagnose) and none feels redundant.
The surface covers generation, inspection, validation, execution, reporting, CI/CD, test data, and failure diagnosis — a full lifecycle. Minor gaps: there is no tool to apply/persist the corrected script that analyze_newman_failure suggests, and no explicit collection-editing or environment-management operation.
Maintenance
Related MCP Connectors
AI-callable tools for API mocking, testing, monitoring, security, and automation.
30+ deterministic dev and delivery tools: linting, metrics, diagrams, model advice, AI-text checks.
Free AI test helpers: injection inputs, OWASP mapping, release plans, response and tool-call packs.
End-to-end API testing — generate and run tests from OpenAPI, curl, Postman, or real user traffic.
Related MCP Servers
- AlicenseBqualityCmaintenanceEnables running Postman collections using Newman for conducting API tests and obtaining detailed result analysis via a standardized interface.184MIT
- AlicenseBqualityDmaintenanceAutomatically generates Postman collections from code directories by analyzing API endpoints and parameters, enabling easy testing, documentation, and sharing.143MIT
- AlicenseNot gradedqualityCmaintenanceExposes 11 agent-native QA tools over stdio so coding agents can discover a project, analyze risk, select the smallest relevant test set, generate and dry-run tests, triage failures, propose tiered heals, analyze flakes, generate quality reports, and evaluate release readiness. Planning and healing tools stay read-only or propose-only, while execution defaults to dry-run, keeping agent actions safe and evidence-backed.MIT
- AlicenseNot gradedqualityCmaintenanceEnables AI agents to import and export Postman collections, author and execute API requests, run collection tests with pm.* scripts, manage environments and request history, and inspect legacy Postman data through 23 structured tools.5MIT