MCP 服务器

Postman MCP Server

Enables interaction with Postman workspaces, collections, requests, responses, and monitors through the Postman API. Allows users to manage API collections, create and update requests/responses, and execute monitors directly from chat.

README

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

Clone this repository and install dependencies:
```
cd postman-mcp
npm install
```

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=

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!