Skip to content

Commit e2f238f

Browse files
akinard-postmangarciasdoschristosgkoros
authored
[PSTAPI-798] Improve README documentation (#42)
* initial README updates PSTAPI-798 Initial updates for https://postmanlabs.atlassian.net/browse/PSTAPI-798. * Update README.md Updates per Christos' feedback. * review updates and add eu notes * Update README.md Add mention of min/full at intro. * Update README.md Updates for PSTAPI-830 comments * Update README.md * Update README.md Remove line about enabling Agent mode. * fix: `.dxt` <> `.mcpb` extension * Update README.md Updates for remote/local server updates. * updating readme with gemini installation; adding mcp registry manifest; fix gemin extension manifest; * Update README.md Minor edits for formatting --------- Co-authored-by: Diego García <[email protected]> Co-authored-by: Christos Gkoros <[email protected]>
1 parent 2045a87 commit e2f238f

File tree

3 files changed

+191
-68
lines changed

3 files changed

+191
-68
lines changed

‎README.md‎

Lines changed: 158 additions & 68 deletions
Original file line numberDiff line numberDiff line change
@@ -1,101 +1,80 @@
11
# Postman MCP Server
22

3-
This project offers the following Model Context Protocol (MCP) server options:
3+
The Postman MCP Server connects Postman to AI tools, giving AI agents and assistants the ability to access workspaces, manage collections and environments, evaluate APIs, and automate workflows through natural language interactions.
44

5-
- [**STDIO**](#stdio)
6-
- [**Streamable HTTP**](#streamable-http)
5+
Postman supports the following tool configurations:
76

8-
For more information about the available transports, see the [MCP specification](https://modelcontextprotocol.io/docs/concepts/transports).
7+
- **Minimal** — (Default) Only includes essential tools for basic Postman operations This offers faster performance and simplifies use for those who only need basic Postman operations. Ideal for users who want to modify a single Postman elements, such as collections, workspaces, or environments.
8+
- **Full** — Includes all available Postman API tools (100+ tools). This configuration is ideal for users who engage in advanced collaboration and Postman's Enterprise features.
99

10-
## STDIO
10+
### Use Cases
1111

12-
This is a lightweight solution that's ideal for integration with editors and tools like [VS Code](https://code.visualstudio.com/).
12+
- **Code synchronization** - Effortlessly keep your code in sync with your Postman collections and specs.
13+
- **Collection management** - Create and tag collections, update collection and request documentation, add comments, or perform actions across multiple collections without leaving your editor.
14+
- **Workspace and environment management** - Create workspaces and environments, plus manage your environment variables.
15+
- **Automatic spec creation** - Create [specs](https://learning.postman.com/docs/design-apis/specifications/overview/) from your code and use them to generate Postman collections.
1316

14-
> For Docker set up and installation, see [DOCKER.md](./DOCKER.md).
17+
Designed for developers who want to integrate their AI tools with Postman’s context and features. Supports quick natural language queries queries to advanced agent workflows.
1518

16-
### VS Code integration
19+
### Support for EU
1720

18-
> **Note:**
19-
> By default, this server provides 37 tools (minimal mode). Use the `--full` flag to access all 106 tools.
20-
> Use the `--region` flag to specify the Postman API region (`us` or `eu`), or set the `POSTMAN_API_BASE_URL` environment variable directly.
21+
The Postman MCP Server supports the EU region for remote and local servers:
22+
- For streamable HTTP, the remote server is available at `https://mcp.eu.postman.com`.
23+
- For our STDIO public package, use the `--region` flag to specify the Postman API region (`us` or `eu`), or set the `POSTMAN_API_BASE_URL` environment variable directly.
2124

22-
Integrate your MCP server with Visual Studio Code and use it with VS Code extensions that support MCP. To do this, do the following:
25+
---
2326

24-
1. Create a *.vscode/mcp.json* file in your project and enter the following:
27+
### Contents
2528

26-
```json
27-
{
28-
"servers": {
29-
"postman-api-mcp": {
30-
"type": "stdio",
31-
"command": "npx",
32-
"args": [
33-
"@postman/postman-mcp-server",
34-
"--full" // (optional) Use this flag to enable full mode
35-
],
36-
"env": {
37-
"POSTMAN_API_KEY": "${input:postman-api-key}"
38-
}
39-
}
40-
},
41-
"inputs": [
42-
{
43-
"id": "postman-api-key",
44-
"type": "promptString",
45-
"description": "Enter your Postman API key"
46-
}
47-
]
48-
}
49-
```
50-
51-
1. Install an MCP-compatible VS Code extension, such as GitHub Copilot, Claude for VS Code, or other AI assistants that support MCP.
52-
53-
#### Configure the extension
54-
55-
Configure the extension to use the **postman-api-mcp** server, a local STDIO-based server that runs directly from your project files:
29+
- [**Remote server**](#remote-server)
30+
- [**Prerequisites**](#prerequisites)
31+
- [**VS Code**](#install-in-vs-code)
32+
- [**Cursor**](#install-in-cursor)
33+
- [**Local server**](#local-server)
34+
- [**Prerequisites**](#prerequisites-1)
35+
- [**Configuration**](#configuration)
36+
- [**VS Code**](#install-in-vs-code-1)
37+
- [**Cursor**](#install-in-cursor-1)
38+
- [**Claude**](#claude-integration)
39+
- [**Gemini CLI**](#use-as-a-gemini-cli-extension)
40+
- [**Questions and support**](#questions-and-support)
41+
- [**Migration from Postman MCP Server v1 to v2**](#migration-from-v1x-to-v2x)
5642

57-
1. Clone the **postman-mcp-server** repository.
58-
1. In the repository's root folder, run the `npm install` command. This installs all the required dependencies.
59-
1. Replace `${workspaceFolder}` in the *mcp.json* file with the full path to the Postman MCP repository.
60-
1. When prompted, enter your [Postman API key](https://go.postman.co/settings/me/api-keys).
43+
---
6144

62-
### Claude integration
45+
## Remote server
6346

64-
To integrate the MCP server with Claude, check the latest [Postman MCP server release](https://github.com/postmanlabs/postman-mcp-server/releases) and download one of the following `.dxt` files:
47+
The remote Postman MCP Server is hosted by Postman over streamable HTTP and provides the easiest method for getting started. If your MCP host doesn't support remote MCP servers, you can use the [local Postman MCP Server](#local-server).
6548

66-
- **postman-api-mcp-minimal.dxt** - Contains 37 essential tools for basic Postman operations.
67-
- **postman-api-mcp-full.dxt** - Contains all 106+ tools for comprehensive Postman functionality.
49+
The remote server supports the following tool configurations:
6850

69-
For more information, see Anthropic's [Claude Desktop Extensions](https://www.anthropic.com/engineering/desktop-extensions) documentation.
70-
71-
## Streamable HTTP
51+
- **Minimal** — (Default) Only includes essential tools for basic Postman operations, available at `https://mcp.postman.com/minimal`.
52+
- **Full** — Includes all available Postman API tools (100+ tools), available at `https://mcp.postman.com/mcp`.
7253

73-
The streamable HTTP version is available at `https://mcp.postman.com`. It supports two tool configurations to better serve different use cases:
54+
**Note:** The remote EU HTTP server is available at `https://mcp.eu.postman.com`.
7455

75-
- **Minimal** — Only includes essential tools for basic Postman operations, available at `https://mcp.postman.com/minimal`. This offers faster performance and simplifies use for those who only need basic Postman operations.
76-
- **Full** — Includes all available Postman API tools (100+ tools), available at `https://mcp.postman.com/mcp`.
56+
### Prerequisites
7757

78-
> **Note:** The streamable EU HTTP server is available at `https://mcp.eu.postman.com`.
58+
Before getting started, make certain you have a valid [Postman API Key](https://postman.postman.co/settings/me/api-keys).
7959

80-
### Cursor integration
60+
### Install in VS Code
8161

82-
To integrate the MCP server with Cursor, click the following button:
83-
> Ensure the Authorization header uses the Bearer <YOUR_API_KEY> format.
62+
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install_Server-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://insiders.vscode.dev/redirect/mcp/install?name=postman_mcp_server&config=%7B%22type%22%3A%20%22http%22%2C%22url%22%3A%20%22https%3A%2F%2Fmcp.postman.com%2Fminimal%22%2C%22headers%22%3A%7B%22Authorization%22%3A%22Bearer%20YOUR_API_KEY%22%7D%7D)
8463

85-
[![Install the Postman MCP Server](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en/install-mcp?name=postman_mcp_server&config=eyJ1cmwiOiJodHRwczovL21jcC5wb3N0bWFuLmNvbS9taW5pbWFsIiwiaGVhZGVycyI6eyJBdXRob3JpemF0aW9uIjoiQmVhcmVyIFlPVVJfQVBJX0tFWSJ9fQ%3D%3D)
64+
To install the remote Postman MCP Server in Visual Studio Code, click the install button or use the [Postman VS Code Extension](https://marketplace.visualstudio.com/items?itemName=Postman.postman-for-vscode).
8665

87-
### VS Code integration
66+
**Note:** By default, the server provides 37 tools. Use full mode (`https://mcp.postman.com/mcp`) to access all 106 tools.
8867

89-
> By default, the server provides 37 tools. Use **Full** (`https://mcp.postman.com/mcp`) mode to access all 106 tools.
68+
#### Manual configuration
9069

91-
To install in VS Code, you can use the [Postman VS Code Extension](https://marketplace.visualstudio.com/items?itemName=Postman.postman-for-vscode). Or you can add the following to the *.vscode/mcp.json* file:
70+
To manually configure the remote Postman MCP Server in VS Code, add the following JSON block to the *.vscode/mcp.json* file:
9271

9372
```json
9473
{
9574
"servers": {
9675
"postman-api-http-server": {
9776
"type": "http",
98-
"url": "https://mcp.postman.com/{minimal | mcp}", // choose "minimal" or "mcp"
77+
"url": "https://mcp.postman.com/{minimal | mcp}", // use "minimal" (default) or "mcp" (full)
9978
"headers": {
10079
"Authorization": "Bearer ${input:postman-api-key}"
10180
}
@@ -113,19 +92,130 @@ To install in VS Code, you can use the [Postman VS Code Extension](https://marke
11392

11493
When prompted, enter your Postman API key. Afterwards, the agent performs calls to the Postman cloud MCP server at `https://mcp.postman.com`.
11594

95+
### Install in Cursor
96+
97+
[![Install in Cursor](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en/install-mcp?name=postman_mcp_server&config=eyJ1cmwiOiJodHRwczovL21jcC5wb3N0bWFuLmNvbS9taW5pbWFsIiwiaGVhZGVycyI6eyJBdXRob3JpemF0aW9uIjoiQmVhcmVyIFlPVVJfQVBJX0tFWSJ9fQ%3D%3D)
98+
99+
To install the remote Postman MCP Server in Cursor, click the install button.
100+
101+
**Note:** Ensure that the Authorization header uses the `Bearer <YOUR_API_KEY>` format.
102+
103+
---
104+
105+
## Local server
106+
107+
If remote MCP servers aren't supported by your MCP host, you can install the Postman MCP Server to your local machine.
108+
109+
STDIO is a lightweight solution that's ideal for integration with editors and tools like Visual Studio Code. Install an MCP-compatible VS Code extension, such as GitHub Copilot, Claude for VS Code, or other AI assistants that support MCP.
110+
111+
[![Install GitHub Copilot](https://img.shields.io/badge/Install-GitHub%20Copilot-black?style=for-the-badge&logo=github)](vscode:extension/GitHub.copilot) [![Install Claude for VS Code](https://img.shields.io/badge/Install-Claude%20for%20VS%20Code-orange?style=for-the-badge&logo=anthropic)](vscode:extension/Anthropic.claude-dev)
112+
113+
**Note:** For Docker set up and installation, see [DOCKER.md](./DOCKER.md).
114+
115+
The local server supports the following tool configurations:
116+
117+
- **Minimal** — (Default) Only includes essential tools for basic Postman operations.
118+
- **Full** — Includes all available Postman API tools (100+ tools). Use the `--full` flag to enable this configuration.
119+
120+
### Prerequisites
121+
122+
Before getting started, you'll need the following:
123+
124+
1. To run the server as a Node application, install [Node.js](https://nodejs.org/en).
125+
1. A valid [Postman API Key](https://postman.postman.co/settings/me/api-keys).
126+
127+
### Configuration
128+
129+
To configure the extension to use the local Postman MCP Server, do the following:
130+
131+
1. Clone the **postman-mcp-server** repository.
132+
1. In the repository's root folder, run the `npm install` command. This installs all the required dependencies.
133+
1. Replace `${workspaceFolder}` in the *mcp.json* file with the full path to the Postman MCP repository.
134+
1. When prompted, enter your Postman API key.
135+
136+
### Install in VS Code
137+
138+
[![Install with Node in VS Code](https://img.shields.io/badge/VS_Code-Install_Server-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://insiders.vscode.dev/redirect/mcp/install?name=postman-api-mcp&inputs=%5B%7B%22id%22%3A%22postman-api-key%22%2C%22type%22%3A%22promptString%22%2C%22description%22%3A%22Enter%20your%20Postman%20API%20key%22%7D%5D&config=%7B%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22%40postman%2Fpostman-mcp-server%22%2C%22--full%22%5D%2C%22env%22%3A%7B%22POSTMAN_API_KEY%22%3A%22%24%7Binput%3Apostman-api-key%7D%22%7D%7D)
139+
140+
To install the local Postman MCP Server in Visual Studio Code, click the install button.
141+
142+
**Note:**
143+
- By default, this server provides 37 tools (minimal mode). Use the `--full` flag to access all 106 tools.
144+
- Use the `--region` flag to specify the Postman API region (`us` or `eu`), or set the `POSTMAN_API_BASE_URL` environment variable directly. By default, the server uses the `us` option.
145+
146+
#### Manual configuration
147+
148+
You can manually integrate your MCP server with VS Code to use it with extensions that support MCP. To do this, create a *.vscode/mcp.json* file in your project and add the following JSON block to it:
149+
150+
```json
151+
{
152+
"servers": {
153+
"postman-api-mcp": {
154+
"type": "stdio",
155+
"command": "npx",
156+
"args": [
157+
"@postman/postman-mcp-server",
158+
"--full" // (optional) Use this flag to enable full mode
159+
],
160+
"env": {
161+
"POSTMAN_API_KEY": "${input:postman-api-key}"
162+
}
163+
}
164+
},
165+
"inputs": [
166+
{
167+
"id": "postman-api-key",
168+
"type": "promptString",
169+
"description": "Enter your Postman API key"
170+
}
171+
]
172+
}
173+
```
174+
175+
### Install in Cursor
176+
177+
<!-- Does this section require further set up instruction? -->
178+
179+
[![Install with Node in Cursor](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en/install-mcp?name=postman-api-mcp&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyJAcG9zdG1hbi9wb3N0bWFuLW1jcC1zZXJ2ZXIiLCItLWZ1bGwiXSwiZW52Ijp7IlBPU1RNQU5fQVBJX0tFWSI6IllPVVJfQVBJX0tFWSJ9fQ%3D%3D)
180+
181+
To install the local Postman MCP Server in Cursor, click the install button.
182+
183+
### Claude integration
184+
185+
To integrate the MCP server with Claude, check the latest [Postman MCP Server release](https://github.com/postmanlabs/postman-mcp-server/releases) and get the `.mcpb` file.
186+
187+
* `postman-api-mcp-minimal.mcpb` - Contains the 37 essential tools for common Postman operations.
188+
* `postman-api-mcp-full.mcpb` - Contains all available Postman tools.
189+
190+
For more information, see Anthropic's [Claude Desktop Extensions](https://www.anthropic.com/engineering/desktop-extensions) documentation.
191+
192+
### Use as a Gemini CLI extension
193+
194+
To install the MCP server as a Gemini CLI extension, run the following command in your terminal:
195+
196+
```bash
197+
gemini extensions install https://github.com/postmanlabs/postman-mcp-server
198+
```
199+
200+
---
201+
116202
## Migration from v1.x to v2.x
117203

204+
If you're migrating from Postman MCP Server version 1.x to 2.x, be aware of the following:
205+
118206
- **Tool naming changes** - All tool names changed from kebab-case to camelCase. For example:
119207
- `create-collection` → `createCollection`
120208
- `get-workspaces` → `getWorkspaces`
121209
- `delete-environment` → `deleteEnvironment`
122210
- **Tool availability changes**
123-
- The default (Minimal) behavior provides only 37 essential tools.
211+
- The default (minimal) behavior provides only 37 essential tools.
124212
- The `--full` flag provides access to all 106 tools.
125213

214+
---
215+
126216
## Questions and support
127217

128218
- See the [Postman Agent Generator](https://postman.com/explore/agent-generator) page for updates and new capabilities.
129219
- See [Add your MCP requests to your collections](https://learning.postman.com/docs/postman-ai-agent-builder/mcp-requests/overview/) to learn how to use Postman to perform MCP requests.
130220
- Visit the [Postman Community](https://community.postman.com/) to share what you've built, ask questions, and get help.
131-
- You can connect to both HTTP and STDIO servers and test them using the [Postman MCP Server collection](https://www.postman.com/postman/postman-public-workspace/collection/681dc649440b35935978b8b7).
221+
- You can connect to both the remote and local servers and test them using the [Postman MCP Server collection](https://www.postman.com/postman/postman-public-workspace/collection/681dc649440b35935978b8b7).

‎gemini-extensions.json‎ renamed to ‎gemini-extension.json‎

File renamed without changes.

0 commit comments

Comments
 (0)