Postman Collection Generator MCP

A Model Context Protocol (MCP) utility designed to ingest definitions from various backend frameworks (such as NestJS, FastAPI, or Flask endpoints) and materialize them as executable Postman Collections and associated Environment files.

This capability allows for immediate, automated configuration of Postman for continuous integration and developer testing routines.

Core Capabilities

• Serialization of REST endpoint definitions into Postman Collection format.
• Synchronization of runtime configuration values into Postman Environment specifications.
• Native support for diverse security protocols (e.g., OAuth, Bearer Token mechanisms).
• Sophisticated logic for merging incoming endpoint data with pre-existing collection structures.
• Secure management and abstraction of sensitive key-value pairs designated for environments.
• Dual operational modes: standard input/output (stdio) and Server-Sent Events (SSE).

Operational Prerequisites

• Dependency on the Bun runtime environment (version 1.2.2 minimum).
• A valid Postman Secret API Key.
• The unique identifier for the target Postman Workspace.

Deployment and Invocation

This service operates as an MCP stdio server, necessitating Postman workspace credentials to perform write operations (creation/modification of collections and environments).

Installation via Smithery

For seamless integration into supported IDEs via Smithery:

bash npx -y @smithery/cli install @runninghare/rest-to-postman-mcp --client claude

Direct Execution via npx

Executing the server directly using npx requires passing credentials explicitly:

bash npx -y rest-to-postman@latest --postman-api-key YOUR_SECRET_KEY --postman-workspace-id YOUR_WORKSPACE_UID

Alternatively, leverage environment variables for credential provisioning: bash export POSTMAN_API_KEY=your_api_key export POSTMAN_ACTIVE_WORKSPACE_ID=your_workspace_id npx -y rest-to-postman@latest

This utility is compatible with several advanced AI-integrated coding environments: - Claude Desktop - Cursor - Windsurf - Roo Cline Editor

Crucial Reminder: The service is non-functional without valid Postman API credentials (Key and Workspace ID).

Available Functionality

The server exposes two primary functional interfaces:

1. Environment Synchronization (rest_to_postman_env)

Handles the creation or update of a designated Postman environment, populating it with application variables.

Required Arguments: - envName (string): The designated label for the Postman environment. - envVars (object): A map structure detailing the variable names and their corresponding values.

Example Data Structure:

{ "envName": "Production Configuration", "envVars": { "BASE_ENDPOINT": "https://api.production.net", "ACCESS_SECRET": "secure-token-xyz" } }

2. Collection Assembly (rest_to_postman_collection)

Manages the population or modification of a Postman collection file, detailing all the exposed API methods.

Required Arguments: - collectionRequest (object): A comprehensive Postman v2.1 structure comprising: - info: Metadata for the collection. - auth: Global authentication settings to be applied across requests. - item: An array containing the definitions of individual API calls.

Example Data Structure (Partial):

{ "info": { "name": "Service API Map", "description": "Endpoints derived from codebase analysis", "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json" }, "auth": { "type": "bearer", "bearer": [ {
"key": "Authorization", "value": "Bearer {{ACCESS_SECRET}}", "type": "string" } ] },
"item": [ { "name": "Retrieve All Records", "request": { "method": "GET",
"url": { "raw": "{{BASE_ENDPOINT}}/records", "protocol": "https", "host": ["api", "production", "net"], "path": ["records"] }
} } ] }

Operational Feedback

Both tooling functions yield a confirmation message detailing the successful persistence or modification of the respective Postman artifact:

{ "content": [{ "type": "text", "text": "Successfully synchronized Postman environment: Production Configuration" }] }

Usage Example in Cursor IDE

Demonstration of generating a Postman Collection based on a TypeScript controller file within a NestJS project.

Input Prompt: code Generate the Postman collection named "Campaign Orchestration" derived from this NestJS controller definition. The designated base URL is http://localhost:7022. The collection must enforce a standardized Bearer token authorization header for all included operations.

Resulting Postman Collection Output:

Observe that all methods defined in the Campaign Controller are mapped correctly, and the prerequisite Bearer authentication configuration is globally applied.

Development Workflow

Local Setup Procedures

1. Clone the repository source: bash git clone https://github.com/runninghare/rest-to-postman.git cd rest-to-postman

2. Install required package dependencies: bash bun install

3. Configure local secrets via a .env file: env POSTMAN_API_KEY=your_api_key_here POSTMAN_ACTIVE_WORKSPACE_ID=your_workspace_id_here

Development Execution Mode

To run the server interactively using Bun during active development:

bash

Default execution mode (stdio)

bun run src/mcp.ts

Execution using Server-Sent Events protocol

bun run src/mcp.ts --sse

Project Compilation

To generate the optimized, bundled output:

bash bun run build

This command places the compiled assets within the dist directory.

Available Scripts

• bun run build: Compiles and bundles the source code.
• bun run dev: Initiates the server in a continuous development environment.
• bun run startSSE: Launches the server configured for SSE transport.

Collaboration Guidelines

We welcome external contributions. Please submit any proposed enhancements or corrections via a Pull Request.

Licensing Information

This software is distributed under the terms of the MIT License (refer to the LICENSE file for comprehensive details).