README.md•6 kB
# Postman MCP Server
Expose the [Postman API](https://api.getpostman.com) 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](https://schema.getpostman.com/json/collection/v2.1.0/collection.json). 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:
```bash
cd postman-mcp
npm install
```
2. Copy `.env.example` to `.env` and add your Postman API key and (optionally) a default workspace:
```ini
POSTMAN_API_KEY=pmak-xxxxxxxxxxxxxxxxxxxx
POSTMAN_BASE_URL=https://api.getpostman.com
DEFAULT_WORKSPACE_ID=
```
3. Run the server in development mode:
```bash
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:
```bash
docker compose run -e POSTMAN_API_KEY=pmak-xxx postman-mcp
```
### Integrating with Codex (VS Code)
Add an entry to your `~/.codex/config.toml`:
```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:
```json
listWorkspaces {}
```
Create a new collection in a workspace:
```json
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:
```json
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:
```json
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:
```json
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!