Skip to main content
Glama

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 build

The built server is dist/index.js. Start it directly with:

node dist/index.js

To run the test suite:

npm test

Install from npm

After the package is published, install it in a project:

npm install newman-ai-mcp

Or run a CLI command without installing it globally:

npx newman-ai-mcp --help
npx newman-ai-mcp --check-llm

The 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-llm

For 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

NEWMAN_MCP_LLM_PROVIDER

Set to openai-compatible.

NEWMAN_MCP_LLM_BASE_URL

API base URL, for example https://api.openai.com/v1.

NEWMAN_MCP_LLM_API_KEY

API key. Keep it in the environment or a secret manager; do not put it in source control.

NEWMAN_MCP_LLM_MODEL

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 test

License

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 tools
analyze_newman_failureAnalyze Newman failureB
Read-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 collectionA
Read-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 collectionA
Read-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

    A3.6/5.0

    Scored across 9 tools

    Disambiguation4/5

    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.

    Naming Consistency5/5

    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.

    Tool Count5/5

    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.

    Completeness4/5

    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

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      B
      quality
      C
      maintenance
      Enables running Postman collections using Newman for conducting API tests and obtaining detailed result analysis via a standardized interface.
      1
      84
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Exposes 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
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables 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.
      5
      MIT