@postman/postman-mcp-server 2.3.3 → 2.3.7
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +188 -68
- package/dist/package.json +1 -1
- package/dist/src/index.js +10 -1
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,101 +1,82 @@
|
|
|
1
1
|
# Postman MCP Server
|
|
2
2
|
|
|
3
|
-
|
|
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.
|
|
4
4
|
|
|
5
|
-
|
|
6
|
-
- [**Streamable HTTP**](#streamable-http)
|
|
5
|
+
Postman supports the following tool configurations:
|
|
7
6
|
|
|
8
|
-
|
|
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.
|
|
9
9
|
|
|
10
|
-
|
|
10
|
+
### Use Cases
|
|
11
11
|
|
|
12
|
-
|
|
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.
|
|
13
16
|
|
|
14
|
-
|
|
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.
|
|
15
18
|
|
|
16
|
-
###
|
|
19
|
+
### Support for EU
|
|
17
20
|
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
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.
|
|
21
24
|
|
|
22
|
-
|
|
25
|
+
---
|
|
23
26
|
|
|
24
|
-
|
|
27
|
+
### Contents
|
|
25
28
|
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
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.
|
|
29
|
+
- [**Remote server**](#remote-server)
|
|
30
|
+
- [**Prerequisites**](#prerequisites)
|
|
31
|
+
- [**VS Code**](#install-in-vs-code)
|
|
32
|
+
- [**Cursor**](#install-in-cursor)
|
|
33
|
+
- [**Claude Code**](#install-in-claude-code)
|
|
34
|
+
- [**Local server**](#local-server)
|
|
35
|
+
- [**Prerequisites**](#prerequisites-1)
|
|
36
|
+
- [**Configuration**](#configuration)
|
|
37
|
+
- [**VS Code**](#install-in-vs-code-1)
|
|
38
|
+
- [**Cursor**](#install-in-cursor-1)
|
|
39
|
+
- [**Claude**](#claude-integration)
|
|
40
|
+
- [**Claude Code**](#install-in-claude-code-1)
|
|
41
|
+
- [**Gemini CLI**](#use-as-a-gemini-cli-extension)
|
|
42
|
+
- [**Questions and support**](#questions-and-support)
|
|
43
|
+
- [**Migration from Postman MCP Server v1 to v2**](#migration-from-v1x-to-v2x)
|
|
52
44
|
|
|
53
|
-
|
|
45
|
+
---
|
|
54
46
|
|
|
55
|
-
|
|
47
|
+
## Remote server
|
|
56
48
|
|
|
57
|
-
|
|
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).
|
|
49
|
+
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).
|
|
61
50
|
|
|
62
|
-
|
|
63
|
-
|
|
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:
|
|
65
|
-
|
|
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.
|
|
68
|
-
|
|
69
|
-
For more information, see Anthropic's [Claude Desktop Extensions](https://www.anthropic.com/engineering/desktop-extensions) documentation.
|
|
51
|
+
The remote server supports the following tool configurations:
|
|
70
52
|
|
|
71
|
-
|
|
53
|
+
- **Minimal** — (Default) Only includes essential tools for basic Postman operations, available at `https://mcp.postman.com/minimal`.
|
|
54
|
+
- **Full** — Includes all available Postman API tools (100+ tools), available at `https://mcp.postman.com/mcp`.
|
|
72
55
|
|
|
73
|
-
The
|
|
56
|
+
**Note:** The remote EU HTTP server is available at `https://mcp.eu.postman.com`.
|
|
74
57
|
|
|
75
|
-
|
|
76
|
-
- **Full** — Includes all available Postman API tools (100+ tools), available at `https://mcp.postman.com/mcp`.
|
|
58
|
+
### Prerequisites
|
|
77
59
|
|
|
78
|
-
|
|
60
|
+
Before getting started, make certain you have a valid [Postman API Key](https://postman.postman.co/settings/me/api-keys).
|
|
79
61
|
|
|
80
|
-
###
|
|
62
|
+
### Install in VS Code
|
|
81
63
|
|
|
82
|
-
|
|
83
|
-
> Ensure the Authorization header uses the Bearer <YOUR_API_KEY> format.
|
|
64
|
+
[](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)
|
|
84
65
|
|
|
85
|
-
|
|
66
|
+
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).
|
|
86
67
|
|
|
87
|
-
|
|
68
|
+
**Note:** By default, the server provides 37 tools. Use full mode (`https://mcp.postman.com/mcp`) to access all 106 tools.
|
|
88
69
|
|
|
89
|
-
|
|
70
|
+
#### Manual configuration
|
|
90
71
|
|
|
91
|
-
To
|
|
72
|
+
To manually configure the remote Postman MCP Server in VS Code, add the following JSON block to the *.vscode/mcp.json* file:
|
|
92
73
|
|
|
93
74
|
```json
|
|
94
75
|
{
|
|
95
76
|
"servers": {
|
|
96
77
|
"postman-api-http-server": {
|
|
97
78
|
"type": "http",
|
|
98
|
-
"url": "https://mcp.postman.com/{minimal | mcp}", //
|
|
79
|
+
"url": "https://mcp.postman.com/{minimal | mcp}", // use "minimal" (default) or "mcp" (full)
|
|
99
80
|
"headers": {
|
|
100
81
|
"Authorization": "Bearer ${input:postman-api-key}"
|
|
101
82
|
}
|
|
@@ -113,19 +94,158 @@ To install in VS Code, you can use the [Postman VS Code Extension](https://marke
|
|
|
113
94
|
|
|
114
95
|
When prompted, enter your Postman API key. Afterwards, the agent performs calls to the Postman cloud MCP server at `https://mcp.postman.com`.
|
|
115
96
|
|
|
97
|
+
### Install in Cursor
|
|
98
|
+
|
|
99
|
+
[](https://cursor.com/en/install-mcp?name=postman_mcp_server&config=eyJ1cmwiOiJodHRwczovL21jcC5wb3N0bWFuLmNvbS9taW5pbWFsIiwiaGVhZGVycyI6eyJBdXRob3JpemF0aW9uIjoiQmVhcmVyIFlPVVJfQVBJX0tFWSJ9fQ%3D%3D)
|
|
100
|
+
|
|
101
|
+
To install the remote Postman MCP Server in Cursor, click the install button.
|
|
102
|
+
|
|
103
|
+
**Note:** Ensure that the Authorization header uses the `Bearer <YOUR_API_KEY>` format.
|
|
104
|
+
|
|
105
|
+
### Install in Claude Code
|
|
106
|
+
|
|
107
|
+
To install the MCP server in Claude Code, run the following command in your terminal:
|
|
108
|
+
|
|
109
|
+
**Minimal**
|
|
110
|
+
|
|
111
|
+
```bash
|
|
112
|
+
claude mcp add --transport http postman https://mcp.postman.com/minimal
|
|
113
|
+
```
|
|
114
|
+
|
|
115
|
+
**Full**
|
|
116
|
+
```bash
|
|
117
|
+
claude mcp add --transport http postman https://mcp.postman.com/mcp
|
|
118
|
+
```
|
|
119
|
+
|
|
120
|
+
---
|
|
121
|
+
|
|
122
|
+
## Local server
|
|
123
|
+
|
|
124
|
+
If remote MCP servers aren't supported by your MCP host, you can install the Postman MCP Server to your local machine.
|
|
125
|
+
|
|
126
|
+
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.
|
|
127
|
+
|
|
128
|
+
**Note:** For Docker set up and installation, see [DOCKER.md](./DOCKER.md).
|
|
129
|
+
|
|
130
|
+
The local server supports the following tool configurations:
|
|
131
|
+
|
|
132
|
+
- **Minimal** — (Default) Only includes essential tools for basic Postman operations.
|
|
133
|
+
- **Full** — Includes all available Postman API tools (100+ tools). Use the `--full` flag to enable this configuration.
|
|
134
|
+
|
|
135
|
+
### Prerequisites
|
|
136
|
+
|
|
137
|
+
Before getting started, you'll need the following:
|
|
138
|
+
|
|
139
|
+
1. To run the server as a Node application, install [Node.js](https://nodejs.org/en).
|
|
140
|
+
1. A valid [Postman API Key](https://postman.postman.co/settings/me/api-keys).
|
|
141
|
+
|
|
142
|
+
### Configuration
|
|
143
|
+
|
|
144
|
+
To configure the extension to use the local Postman MCP Server, do the following:
|
|
145
|
+
|
|
146
|
+
1. Clone the **postman-mcp-server** repository.
|
|
147
|
+
1. In the repository's root folder, run the `npm install` command. This installs all the required dependencies.
|
|
148
|
+
1. Replace `${workspaceFolder}` in the *mcp.json* file with the full path to the Postman MCP repository.
|
|
149
|
+
1. When prompted, enter your Postman API key.
|
|
150
|
+
|
|
151
|
+
### Install in VS Code
|
|
152
|
+
|
|
153
|
+
[](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)
|
|
154
|
+
|
|
155
|
+
To install the local Postman MCP Server in Visual Studio Code, click the install button.
|
|
156
|
+
|
|
157
|
+
**Note:**
|
|
158
|
+
- By default, this server provides 37 tools (minimal mode). Use the `--full` flag to access all 106 tools.
|
|
159
|
+
- 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.
|
|
160
|
+
|
|
161
|
+
#### Manual configuration
|
|
162
|
+
|
|
163
|
+
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:
|
|
164
|
+
|
|
165
|
+
```json
|
|
166
|
+
{
|
|
167
|
+
"servers": {
|
|
168
|
+
"postman-api-mcp": {
|
|
169
|
+
"type": "stdio",
|
|
170
|
+
"command": "npx",
|
|
171
|
+
"args": [
|
|
172
|
+
"@postman/postman-mcp-server",
|
|
173
|
+
"--full" // (optional) Use this flag to enable full mode
|
|
174
|
+
],
|
|
175
|
+
"env": {
|
|
176
|
+
"POSTMAN_API_KEY": "${input:postman-api-key}"
|
|
177
|
+
}
|
|
178
|
+
}
|
|
179
|
+
},
|
|
180
|
+
"inputs": [
|
|
181
|
+
{
|
|
182
|
+
"id": "postman-api-key",
|
|
183
|
+
"type": "promptString",
|
|
184
|
+
"description": "Enter your Postman API key"
|
|
185
|
+
}
|
|
186
|
+
]
|
|
187
|
+
}
|
|
188
|
+
```
|
|
189
|
+
|
|
190
|
+
### Install in Cursor
|
|
191
|
+
|
|
192
|
+
<!-- Does this section require further set up instruction? -->
|
|
193
|
+
|
|
194
|
+
[](https://cursor.com/en/install-mcp?name=postman-api-mcp&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyJAcG9zdG1hbi9wb3N0bWFuLW1jcC1zZXJ2ZXIiLCItLWZ1bGwiXSwiZW52Ijp7IlBPU1RNQU5fQVBJX0tFWSI6IllPVVJfQVBJX0tFWSJ9fQ%3D%3D)
|
|
195
|
+
|
|
196
|
+
To install the local Postman MCP Server in Cursor, click the install button.
|
|
197
|
+
|
|
198
|
+
### Claude integration
|
|
199
|
+
|
|
200
|
+
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.
|
|
201
|
+
|
|
202
|
+
* `postman-api-mcp-minimal.mcpb` - Contains the 37 essential tools for common Postman operations.
|
|
203
|
+
* `postman-api-mcp-full.mcpb` - Contains all available Postman tools.
|
|
204
|
+
|
|
205
|
+
For more information, see Anthropic's [Claude Desktop Extensions](https://www.anthropic.com/engineering/desktop-extensions) documentation.
|
|
206
|
+
|
|
207
|
+
### Install in Claude Code
|
|
208
|
+
|
|
209
|
+
To install the MCP server in Claude Code, run the following command in your terminal:
|
|
210
|
+
|
|
211
|
+
**Minimal**
|
|
212
|
+
|
|
213
|
+
```bash
|
|
214
|
+
claude mcp add postman -- npx @postman/mcp-server@latest
|
|
215
|
+
```
|
|
216
|
+
|
|
217
|
+
**Full**
|
|
218
|
+
```bash
|
|
219
|
+
claude mcp add postman -- npx @postman/mcp-server@latest --full
|
|
220
|
+
```
|
|
221
|
+
|
|
222
|
+
### Use as a Gemini CLI extension
|
|
223
|
+
|
|
224
|
+
To install the MCP server as a Gemini CLI extension, run the following command in your terminal:
|
|
225
|
+
|
|
226
|
+
```bash
|
|
227
|
+
gemini extensions install https://github.com/postmanlabs/postman-mcp-server
|
|
228
|
+
```
|
|
229
|
+
|
|
230
|
+
---
|
|
231
|
+
|
|
116
232
|
## Migration from v1.x to v2.x
|
|
117
233
|
|
|
234
|
+
If you're migrating from Postman MCP Server version 1.x to 2.x, be aware of the following:
|
|
235
|
+
|
|
118
236
|
- **Tool naming changes** - All tool names changed from kebab-case to camelCase. For example:
|
|
119
237
|
- `create-collection` → `createCollection`
|
|
120
238
|
- `get-workspaces` → `getWorkspaces`
|
|
121
239
|
- `delete-environment` → `deleteEnvironment`
|
|
122
240
|
- **Tool availability changes**
|
|
123
|
-
- The default (
|
|
241
|
+
- The default (minimal) behavior provides only 37 essential tools.
|
|
124
242
|
- The `--full` flag provides access to all 106 tools.
|
|
125
243
|
|
|
244
|
+
---
|
|
245
|
+
|
|
126
246
|
## Questions and support
|
|
127
247
|
|
|
128
248
|
- See the [Postman Agent Generator](https://postman.com/explore/agent-generator) page for updates and new capabilities.
|
|
129
249
|
- 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.
|
|
130
250
|
- 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
|
|
251
|
+
- 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).
|
package/dist/package.json
CHANGED
package/dist/src/index.js
CHANGED
|
@@ -83,7 +83,16 @@ async function loadAllTools() {
|
|
|
83
83
|
return [];
|
|
84
84
|
}
|
|
85
85
|
}
|
|
86
|
-
dotenv.config();
|
|
86
|
+
const dotEnvOutput = dotenv.config({ quiet: true });
|
|
87
|
+
if (dotEnvOutput.error) {
|
|
88
|
+
if (dotEnvOutput.error.code !== 'ENOENT') {
|
|
89
|
+
log('error', `Error loading .env file: ${dotEnvOutput.error}`);
|
|
90
|
+
process.exit(1);
|
|
91
|
+
}
|
|
92
|
+
}
|
|
93
|
+
else {
|
|
94
|
+
log('info', `Environment variables loaded: ${dotEnvOutput.parsed ? Object.keys(dotEnvOutput.parsed).length : 0} environment variables: ${Object.keys(dotEnvOutput.parsed || {}).join(', ')}`);
|
|
95
|
+
}
|
|
87
96
|
const SERVER_NAME = packageJson.name;
|
|
88
97
|
const APP_VERSION = packageJson.version;
|
|
89
98
|
export const USER_AGENT = `${SERVER_NAME}/${APP_VERSION}`;
|