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

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.

Related MCP server: Postman MCP Server

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!