Postman MCP Server

Expose the Postman API as a set of [Model‑Context Protocol (MCP)] tools. This project wraps core Postman API endpoints into well‑typed tools that can be invoked by your favourite MCP host (Codex, Claude Desktop, etc.). Use it to list workspaces, manage collections, edit requests and responses (examples) and even run monitors directly from chat.

Features

Tool	Description
listWorkspaces	List every workspace the authenticated API key can access. Uses GET /workspaces【260284429113736†screenshot】.
getWorkspace	Fetch details of a single workspace by ID. Includes arrays of collections, environments, mocks and monitors【260284429113736†screenshot】.
listCollectionsInWorkspace	Given a workspace ID, return the collection references contained in that workspace (UID, name, owner). Internally calls GET /workspaces/{workspaceId} and extracts the collections array.
createCollection	Create a new collection from a Postman Collection v2 object. Accepts an optional workspaceId query parameter to save the collection into a specific workspace【516251068010627†screenshot】.
getCollection	Retrieve a complete collection definition by its UID using GET /collections/{collectionUid}【260252579404281†screenshot】.
updateCollection	Replace an existing collection with a new Collection v2 payload via PUT /collections/{collectionUid}【671023381355334†screenshot】.
createRequest	Add a new request to a collection. Sends POST /collections/{collectionId}/requests with a request object, allowing you to append or insert requests into a collection.
getRequest	Fetch a single request item from a collection with GET /collections/{collectionId}/requests/{requestId} (path variables: collectionId, requestId)【996776406622354†screenshot】.
updateRequest	Replace an existing request definition using PUT /collections/{collectionId}/requests/{requestId}.
createResponse	Create a sample response (example) for a request. Uses POST /collections/{collectionId}/responses?request={requestId} and sends a response body.
getResponse	Get a response example by ID via GET /collections/{collectionId}/responses/{responseId}.
updateResponse	Update an existing example using PUT /collections/{collectionId}/responses/{responseId}.
runMonitor	Execute a monitor synchronously. Invokes POST /monitors/{monitorUid}/run, waits for completion and returns run results【322691760681237†screenshot】.

API constraints

• All endpoints require a valid API key. Set POSTMAN_API_KEY in your environment or .env file.
• The base URL defaults to https://api.getpostman.com but can be overridden with POSTMAN_BASE_URL (useful for EU or India data regions).
• When creating or updating collections, the body must conform to the Postman Collection v2 specification. At a minimum include an info object with a name and an item array.

Getting started

Local development

1. Clone this repository and install dependencies:

   cd postman-mcp
   npm install
   

2. Copy .env.example to .env and add your Postman API key and (optionally) a default workspace:

   POSTMAN_API_KEY=pmak-xxxxxxxxxxxxxxxxxxxx
   POSTMAN_BASE_URL=https://api.getpostman.com
   DEFAULT_WORKSPACE_ID=
   

3. Run the server in development mode:

   npm run dev
   

The server listens on stdin/stdout for JSON‑RPC messages from your MCP host.

Docker

Build and run using the provided Dockerfile:

docker compose run -e POSTMAN_API_KEY=pmak-xxx postman-mcp

Integrating with Codex (VS Code)

Add an entry to your ~/.codex/config.toml:

[mcp_servers.postman]
command = "/usr/local/bin/node"
args = ["/absolute/path/postman-mcp/dist/server.js"]

[mcp_servers.postman.env]
POSTMAN_API_KEY = "pmak-xxx..."
POSTMAN_BASE_URL = "https://api.getpostman.com"
DEFAULT_WORKSPACE_ID = ""

Reload the Codex extension; new tools prefixed with postman will appear in the command palette or chat UI.

Example usage

To list workspaces:

listWorkspaces {}

Create a new collection in a workspace:

createCollection {
  "collection": {
    "info": {
      "name": "Demo API",
      "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json"
    },
    "item": []
  },
  "workspaceId": "8aefd87e-xxxx-4f1a-xxxx-123456789012"
}

Add a request to an existing collection:

createRequest {
  "collectionId": "631e6cfa-59b0-463c-9b89-123456789abc",
  "request": {
    "name": "Get Users",
    "request": {
      "method": "GET",
      "url": {
        "raw": "https://example.com/users",
        "protocol": "https",
        "host": ["example","com"],
        "path": ["users"]
      }
    }
  }
}

Create a sample response for the above request:

createResponse {
  "collectionId": "631e6cfa-59b0-463c-9b89-123456789abc",
  "requestId": "c82dd0c2-4870-4907-8fcb-593a876cf05b",
  "response": {
    "name": "200 OK",
    "status": "OK",
    "code": 200,
    "header": [],
    "body": "{\"message\":\"success\"}"
  }
}

Run a monitor synchronously and view its results:

runMonitor {
  "monitorUid": "9e18469a-2c3d-4a60-8d7f-1234567890ab"
}

Extending

This MCP server intentionally focuses on core Postman entities. You can extend it further by adding tools for:

• Environments – list, create and update environment variables.
• Mocks – manage mock servers and their associated examples.
• Monitors – create, update and delete monitors as well as retrieve run results.
• User information – read API usage and team membership data.

Feel free to fork and add more endpoints to suit your workflow!