Postman MCP Server

Instructions

Implementation Reference

• src/newman/runner.ts:40-79 (handler)

  Core handler function that executes the Newman CLI to run the Postman collection, processes the run summary, extracts test failures, and returns a structured TestResult object.
  async runCollection(options: CollectionRunOptions): Promise<TestResult> { return new Promise((resolve, reject) => { const startTime = new Date().toISOString(); newman.run({ collection: options.collection, environment: options.environment, globals: options.globals, iterationCount: options.iterationCount, reporters: 'cli' }, (err, summary) => { if (err) { reject(err); return; } const endTime = new Date().toISOString(); // Format the results const result: TestResult = { success: summary.run.failures.length === 0, summary: { total: summary.run.stats.tests.total || 0, failed: summary.run.stats.tests.failed || 0, passed: (summary.run.stats.tests.total || 0) - (summary.run.stats.tests.failed || 0) }, failures: (summary.run.failures || []) .map(extractFailureInfo) .filter((failure): failure is TestFailure => failure !== null), timings: { started: startTime, completed: endTime, duration: new Date(endTime).getTime() - new Date(startTime).getTime() } }; resolve(result); }); }); }
• src/server/server.ts:69-101 (handler)

  MCP CallTool request handler specifically for the 'run-collection' tool: checks tool name, validates arguments with Zod schema, calls NewmanRunner.runCollection, and returns formatted text content or error response.
  this.server.setRequestHandler(CallToolRequestSchema, async (request) => { if (request.params.name !== "run-collection") { throw new Error(`Unknown tool: ${request.params.name}`); } // Validate input const args = RunCollectionSchema.parse(request.params.arguments); try { // Run the collection const result = await this.runner.runCollection(args); // Format the response return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] }; } catch (error) { const errorMessage = error instanceof Error ? error.message : String(error); return { content: [{ type: "text", text: JSON.stringify({ error: errorMessage, success: false }, null, 2) }], isError: true }; } });
• src/server/server.ts:37-66 (registration)

  Registers the 'run-collection' tool in the MCP server's ListTools handler, providing name, description, and detailed inputSchema.
  this.server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: [ { name: "run-collection", description: "Run a Postman Collection using Newman", inputSchema: { type: "object", properties: { collection: { type: "string", description: "Path or URL to the Postman collection" }, environment: { type: "string", description: "Optional path or URL to environment file" }, globals: { type: "string", description: "Optional path or URL to globals file" }, iterationCount: { type: "number", description: "Optional number of iterations to run" } }, required: ["collection"] } } ] }));
• src/server/server.ts:7-12 (schema)

  Zod validation schema for 'run-collection' tool inputs, matching the registered inputSchema, used in the tool handler for parsing arguments.
  const RunCollectionSchema = z.object({ collection: z.string(), environment: z.string().optional(), globals: z.string().optional(), iterationCount: z.number().min(1).optional() });
• src/newman/runner.ts:7-32 (helper)

  Helper function to safely parse and extract meaningful test failure details from Newman's raw failure objects, filtering out incomplete data.
  function extractFailureInfo(failure: NewmanRunFailure): TestFailure | null { try { if (!failure.error || !failure.source?.request) { return null; } const { error, source } = failure; const { request } = source; // Ensure we have all required properties if (!error.test || !error.message || !request.method || !request.url) { return null; } return { name: error.test, error: error.message, request: { method: request.method, url: request.url.toString() } }; } catch { return null; } }