Allows execution of Postman collections and folders, running requests, evaluating pm.test assertions, and returning structured results.
Click on "Install 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., "@mcp-postman-runner run folder for ticket PROJ-123"
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.
Run the requests in a Postman collection folder — and get structured, assertion-level results back — straight from your AI assistant.
A Model Context Protocol (MCP) server that executes a
folder of a Postman collection: it resolves {{variables}}, runs the collection + item
pre-request scripts (so token-auth patterns work), previews or fires each request, supports
read and write-method payloads, and evaluates embedded pm.test scripts — then returns status,
timing, request diagnostics, response metadata, body, and per-assertion pass/fail.
It replicates only the slice of newman needed for agent-driven API testing, with no runtime dependencies beyond the MCP SDK and zod.
The Postman connector/API can create requests but can't run them. This server is the execution engine in a Jira → Postman → assess → comment workflow:
Jira ticket ─► derive test cases ─► create a Postman folder (named = ticket key) with pm.test scripts
─► run_folder (this MCP) ─► assess responses ─► comment results on the ticketAny MCP client — Claude Desktop, Claude Cowork, GitHub Copilot (VS Code), Cursor, Windsurf, etc.
Related MCP server: Postman MCP Server
Folder execution — run every request in a folder, in order, sharing variables across the run.
Preflight previews — inspect resolved URLs, methods, redacted headers, body mode/preview, write-request count, and safety warnings before sending any HTTP traffic.
Auth that just works — collection/item pre-request scripts run (incl. pm.sendRequest), so a token fetched once flows to the rest of the folder.
Write-method payload support — execute POST/PUT/PATCH/DELETE tests with raw, JSON, urlencoded, form-data, and GraphQL body modes.
Safety gates — production-like targets and write methods are blocked unless the caller passes explicit approval flags for that run.
Assertion evaluation — the embedded pm.test scripts run via a minimal pm/expect sandbox; you get deterministic pass/fail per assertion.
Structured output — status, time, redacted request diagnostics, response body metadata, truncated response body, and assertion details for each request, ready for an agent to assess.
Credential-less — holds no secrets; the caller passes the collection/environment JSON.
Zero runtime deps — only @modelcontextprotocol/sdk and zod.
Node.js >= 18 (uses the global fetch).
Network access from wherever this runs to the API under test.
A Postman collection (and optional environment) JSON — typically fetched via the Postman API/connector.
Add to your MCP client config:
{
"mcpServers": {
"postman-runner": {
"command": "npx",
"args": ["-y", "mcp-postman-runner@latest"]
}
}
}npx fetches and caches the package on first launch. CLI help: npx -y mcp-postman-runner@latest --help.
Tool | Purpose | Key arguments |
| List folders in a collection (name, id, path, request count) |
|
| Resolve a folder/request without HTTP execution; return redacted targets, bodies, safety warnings, and write counts |
|
| Run every request in a folder; return results + assertions |
|
| Run a single named request (re-run one case) |
|
All tools take the collection JSON (the collection object from the Postman API /
connector's getCollection), and optionally an environment JSON.
Fetch the collection and environment JSON from Postman.
Use list_folders to choose the exact folder.
Use preview_requests to inspect resolved URLs, HTTP methods, redacted auth, body previews,
writeRequests, and safety warnings.
If the target is production-like, get explicit approval for the exact base URL, auth source,
scope/tenant, HTTP methods, and data sensitivity, then pass allowProduction: true with an
approvalNote.
If the folder contains POST/PUT/PATCH/DELETE requests, confirm the environment is safe for
mutation, then pass allowWrites: true with an approvalNote.
Call run_folder or run_request only after the preview is approved.
By default, the runner blocks production-like targets and write methods. This is deliberate: GET/read-only requests can expose real data, and write-method requests can mutate state.
preview_requests result{
"summary": {
"totalRequests": 3,
"methodCounts": { "GET": 1, "POST": 1, "PUT": 1 },
"writeRequests": 2,
"warnings": 0
},
"safety": {
"blocked": true,
"productionLikeTargets": ["https://api.example.com/v1/orders"],
"writeMethods": ["POST", "PUT"],
"warnings": [
"production-like target detected; pass allowProduction with an approval note to execute",
"write methods detected; pass allowWrites after confirming the target is safe for mutation"
],
"approvalNote": null
},
"requests": [
{
"name": "TC-02 create order",
"method": "POST",
"url": "https://api-dev.example.net/v1/orders?api_key=%3Credacted%3E",
"headers": { "Authorization": "<redacted>", "Content-Type": "application/json" },
"body": {
"mode": "raw",
"sent": true,
"contentType": "application/json",
"bytes": 42,
"preview": "{\"name\":\"Demo\",\"password\":\"<redacted>\"}",
"previewTruncated": false
},
"warnings": []
}
]
}run_folder / run_request result{
"summary": {
"totalRequests": 9,
"requestsErrored": 0,
"assertionsTotal": 24,
"assertionsFailed": 4,
"anyFailure": true,
"durationMs": 1420,
"methodCounts": { "GET": 7, "POST": 1, "PUT": 1 },
"statusCounts": { "200": 7, "400": 2 },
"bytesReceived": 21860
},
"results": [
{
"name": "TC-01 Happy path", "method": "GET",
"url": "https://api-dev.example.net/api/v2/countries/states/cities",
"request": {
"method": "GET",
"url": "https://api-dev.example.net/api/v2/countries/states/cities",
"headers": { "Authorization": "<redacted>" },
"body": { "mode": null, "sent": false, "contentType": null, "bytes": null, "preview": null, "previewTruncated": false }
},
"status": 200, "statusText": "OK", "timeMs": 142,
"assertionsPassed": 3, "assertionsFailed": 0,
"assertions": [ { "name": "status is 200", "passed": true, "error": null } ],
"response": { "contentType": "application/json", "bytes": 2186, "bodyTruncated": false },
"responseBody": "{ ... }", // truncated at 20k chars
"warnings": []
}
]
}The runner supports the common Postman body modes used for POST/PUT/PATCH/DELETE tests:
Postman body mode | Runner behavior |
| Resolves variables and sends the raw string. If Postman marks it as JSON, or the body parses as JSON, |
| Sends |
| Sends |
| Sends |
| Request preview/result includes a warning; local file body upload is not implemented. |
Bodies are sent only for methods where HTTP payloads make sense. If a body is defined on GET or
HEAD, the runner omits it and records a warning.
Variables — merges collection variables + environment values; resolves {{var}} (nested, iteratively).
Request build — builds resolved URL, headers, method, body, redacted diagnostics, and safety warnings.
Preview or execute — preview_requests stops after request build; run_folder / run_request continue only if safety gates pass.
Auth / pre-request — execution runs collection-level then item-level pre-request scripts. pm.sendRequest is supported, so the common "POST the auth URL, store the token, reuse it" pattern works; the token is cached in the run's variables.
Request — fires with fetch (per-request timeout), including supported write-method bodies.
Assertions — runs the request's test script through a pm/expect sandbox and records each pm.test result.
pm subsetpm.test, pm.expect (eql/equal/deep, true/false/null, have.property,
at.most/least, above/below, within, include, oneOf, a/an, match, empty,
negation via .not), pm.response.code/.json()/.text(), pm.environment & pm.variables
get/set, and pm.sendRequest. See ARCHITECTURE.md for details.
Add the server to claude_desktop_config.json:
{
"mcpServers": {
"postman-runner": {
"command": "npx",
"args": ["-y", "mcp-postman-runner@latest"]
}
}
}Restart Claude Desktop. A safe prompt pattern is: fetch the Postman collection/environment, call
preview_requests, show the safety summary, and only run the folder after you approve the target.
Register the same npx -y mcp-postman-runner@latest command in your VS Code MCP/tool setup. A
useful Jira-driven flow is:
Fetch the Jira ticket and endpoint contract.
Use a Postman connector to fetch getCollection(model: "full") and getEnvironment(...).
Call list_folders and choose the ticket folder.
Call preview_requests and inspect safety, resolved target URLs, and write-method payloads.
Call run_folder with allowProduction / allowWrites only when explicitly approved.
Ask Copilot to classify results into PASS / FAIL / WARNING / NEEDS-DATA / BLOCKED.
Configure an MCP server named postman-runner with:
{
"command": "npx",
"args": ["-y", "mcp-postman-runner@latest"]
}Then provide the agent with collection/environment JSON from a Postman connector, the Postman API, or sanitized fixtures. This MCP does not authenticate to Postman; it only runs the JSON you pass in.
Use this server alongside a Postman connector:
getCollection(model: "full") → pass the returned collection object here.
getEnvironment(...) → pass the returned environment object when variables/auth are needed.
preview_requests({ collection, environment, folderName }) → inspect resolved requests and safety gates.
run_folder({ collection, environment, folderName, allowWrites, allowProduction, approvalNote }) → execute after approval.
For Jira-driven testing, name the Postman folder after the ticket key so runner results map cleanly back to test-case IDs and ticket comments.
Credential-less by design; secrets in the passed environment are kept in memory for one run and
never logged. Returned diagnostics redact sensitive-looking headers, query parameters, and JSON/form
body keys. Only run collections you trust — their pre-request/pm.test scripts execute in the
server process. See SECURITY.md.
Before running against production or production-like targets, use preview_requests and get
explicit approval for the exact base URL, auth source, scope, methods, and data sensitivity. GET
requests can still expose real data; write methods can mutate state.
See CONTRIBUTING.md. Uses Conventional Commits + semantic-release.
List the folders in a Postman collection (name, id, path, request count). Use to confirm the folder created for a Jira ticket before running it.
| Name | Required | Description | Default |
|---|---|---|---|
| collection | Yes | Postman collection v2.1 JSON (the `collection` object from the Postman API / connector's getCollection). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds value by noting the output fields (name, id, path, request count) but does not disclose additional behavioral traits such as pagination or error behavior. Given the strong annotation coverage, a score of 3 is appropriate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences long, front-loaded with the core function and output fields, followed by a single usage context. No unnecessary words or repetition of schema details.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with one well-schema'd parameter and no output schema, the description covers the essential context: what it lists, what fields are returned, and when to use it. It could mention potential limitations (e.g., no filtering) but is complete for the agent's selection and invocation needs.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% because the single 'collection' parameter is thoroughly described in the schema as a Postman collection v2.1 JSON object. The description adds no additional parameter-level meaning, aligning with the baseline of 3 for high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists folders in a Postman collection and specifies the returned fields (name, id, path, request count). This distinct verb+resource combination differentiates it from sibling tools like run_folder and preview_requests.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit usage context: 'Use to confirm the folder created for a Jira ticket before running it.' This tells the agent when to invoke the tool relative to running a folder. It does not explicitly mention when not to use it or list alternatives, but the guidance is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Resolve variables for a folder or single request without executing HTTP calls. Returns redacted URLs, headers, body mode/preview, method counts, write-request count, and warnings. Use this before run_folder/run_request to confirm targets, auth scope, and write-method safety.
| Name | Required | Description | Default |
|---|---|---|---|
| folderId | No | Explicit folder id (use when folder names are ambiguous). | |
| collection | Yes | Postman collection v2.1 JSON (the `collection` object from the Postman API / connector's getCollection). | |
| folderName | No | Folder name to preview. | |
| allowWrites | No | Explicitly allow POST/PUT/PATCH/DELETE requests for this exact run. | |
| environment | No | Optional Postman environment JSON (the `environment` object from getEnvironment) supplying base URL, auth and variables. | |
| requestName | No | Optional exact request name to preview. | |
| approvalNote | No | Short note naming who/what approved the target and methods. | |
| allowProduction | No | Explicitly allow production-like target URLs/auth URLs for this exact run. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly, openWorld, idempotent, and non-destructive. The description adds value by disclosing the return content (redacted URLs, headers, body mode/preview, method counts, write-request count, warnings) and the fact that it does not execute HTTP calls, which reinforces the safety profile without contradicting annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences: the first defines function and outputs, the second gives usage guidance. Every sentence earns its place, and the most important information is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (8 params, nested objects, no output schema), the description provides a solid summary of return values and the key use case. It doesn't detail all return fields but enough for an agent to form a mental model. The absence of an output schema is partially compensated by listing the return categories.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% parameter description coverage, so the baseline is 3. The description adds minimal extra meaning beyond the schema, mainly reinforcing 'folder or single request' and mentioning environment for auth, but the schema already provides thorough per-parameter descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool resolves variables for a folder or single request without executing HTTP calls, using a specific verb and resource. It also distinguishes itself from sibling tools like run_folder/run_request by explicitly positioning itself as a pre-execution preview.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states when to use this tool: 'Use this before run_folder/run_request to confirm targets, auth scope, and write-method safety.' This directly provides usage context relative to alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Execute every request in a collection folder and return structured results. Resolves {{variables}}, runs the collection + item pre-request scripts (so token auth works), fires each request, and evaluates the embedded pm.test scripts. Target the folder by folderName (typically the Jira ticket key, e.g. 'JIRA-12345') or folderId.
| Name | Required | Description | Default |
|---|---|---|---|
| folderId | No | Explicit folder id (use when folder names are ambiguous). | |
| collection | Yes | Postman collection v2.1 JSON (the `collection` object from the Postman API / connector's getCollection). | |
| folderName | No | Folder name to run (typically the Jira ticket key). | |
| allowWrites | No | Explicitly allow POST/PUT/PATCH/DELETE requests for this exact run. | |
| environment | No | Optional Postman environment JSON (the `environment` object from getEnvironment) supplying base URL, auth and variables. | |
| approvalNote | No | Short note naming who/what approved the target and methods. | |
| allowProduction | No | Explicitly allow production-like target URLs/auth URLs for this exact run. | |
| timeoutRequestMs | No | Per-request timeout in ms (default 30000). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds valuable behavior beyond annotations: it resoles variables, runs pre-request scripts for token auth, fires requests, and evaluates pm.test scripts. Annotations are sparse (readOnlyHint false, destructiveHint false), and the description enriches the safety profile without contradicting it.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two concise sentences. The first sentence front-loads the purpose and behavior, the second explains targeting. No fluff or repetition of schema details.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the core workflow (execution, scripts, return of structured results) and leverages rich schema annotations. It does not detail return structure (no output schema) or safety workflow, but the parameter schema covers those gaps adequately.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3. The description adds useful semantic context for folderName (typically a Jira ticket key) and folderId (for ambiguous names), going beyond the schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Execute') and resource ('collection folder'), and clearly distinguishes from siblings by noting it runs every request and evaluates pm.test scripts. This is a clear, non-tautological purpose statement.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the tool is for running a full folder and provides targeting guidance (folderName typically a Jira key, or folderId). It does not explicitly state exclusions or alternatives, but the context is unambiguous for choosing between this and run_request.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Execute a single named request (optionally scoped to a folder) and return its structured result. Useful for re-running one failing test case.
| Name | Required | Description | Default |
|---|---|---|---|
| folderId | No | ||
| collection | Yes | Postman collection v2.1 JSON (the `collection` object from the Postman API / connector's getCollection). | |
| folderName | No | ||
| allowWrites | No | Explicitly allow POST/PUT/PATCH/DELETE requests for this exact run. | |
| environment | No | Optional Postman environment JSON (the `environment` object from getEnvironment) supplying base URL, auth and variables. | |
| requestName | Yes | Exact request name to run. | |
| approvalNote | No | Short note naming who/what approved the target and methods. | |
| allowProduction | No | Explicitly allow production-like target URLs/auth URLs for this exact run. | |
| timeoutRequestMs | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already declare readOnlyHint false and destructiveHint false, so the agent knows this can perform writes and is not destructive. The description adds little beyond 'execute' and 'structured result,' and does not mention safety gates like allowWrites or approval flows. It does not contradict annotations, but it also does not provide additional behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences with no redundancy. The first sentence front-loads the core action and scope, and the second sentence adds a practical use case. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 9-parameter tool with nested objects and no output schema, the description is minimal. It does not explain the approval workflow (allowWrites, allowProduction, approvalNote) or describe the structure of the 'structured result.' However, the schema provides detailed descriptions for many parameters, partially compensating for the description's brevity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 67%, providing a solid baseline. The description adds some meaning by clarifying that the request can be 'optionally scoped to a folder,' which helps interpret folderId and folderName. However, it does not elaborate on other parameters such as environment, allowProduction, or timeout, which are already documented in the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific action ('Execute a single named request') with an optional scope ('optionally scoped to a folder') and a distinct use case ('re-running one failing test case'). This distinguishes it from sibling tools like run_folder, which would run multiple requests.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides clear context for use ('Useful for re-running one failing test case') but does not explicitly mention when to use run_folder instead. The 'single named request' wording implies the contrast with run_folder, but no alternative tool is named or exclusion is stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Each tool has a clearly distinct purpose: listing folders, previewing without execution, running a folder, and running a single request. The overlap between folder and request scoping is handled by explicit tool names and descriptions, so no ambiguity remains.
All four tool names follow the consistent verb_noun pattern (list_folders, preview_requests, run_folder, run_request) using lowercase with underscores. This makes the tool set predictable and easy to navigate.
Four tools is well-scoped for a Postman runner server. Each tool covers a necessary step in the workflow: discover, preview, execute folder, execute single request, without unnecessary additions.
The tool surface fully covers the domain of running Postman collections: listing folders to identify targets, previewing to verify safety, executing whole folders, and re-running individual requests. No obvious missing operations or dead ends.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
Direct access to Cypress tests results and accessibility reports in your AI workflow.
AI-callable tools for API mocking, testing, monitoring, security, and automation.
End-to-end API testing — generate and run tests from OpenAPI, curl, Postman, or real user traffic.
Drive OctoPerf load testing from any AI agent: import, edit, validate, run scenarios, read metrics.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/tezaswiraj7222/mcp-postman-runner'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
