Postman MCP Server

1# Postman MCP Server
2[![smithery badge](https://smithery.ai/badge/postman-api-server)](https://smithery.ai/server/postman-api-server)
3**Version:** v0.2.0
4 
5An MCP server that provides access to the [Postman](https://www.postman.com/) API. Functionality is based on the [official OpenAPI specification](https://www.postman.com/postman/postman-public-workspace/documentation/i2uqzpp/postman-api). For more information, see the [Postman API documentation](https://www.postman.com/postman-public-workspace/).
6 
7This project is part of the Model Context Protocol (MCP) initiative from Anthropic. For more information, visit the [MCP GitHub repository](https://github.com/modelcontextprotocol) and the announcement on the [Anthropic blog](https://www.anthropic.com/news/model-context-protocol).
8 
9**[Skip ahead to install instructions](#installation)**
10 
11 
12![postman-mcp-server - Cover Image](https://github.com/user-attachments/assets/e19d712f-ad97-4456-a414-d69b159a9ed2)
13 
14 
15> [!WARNING]
16> This project is currently under active development. Please use with caution and expect breaking changes.
17 
18> [!NOTE]
19> AI Generated Code. I used Cline v2.2.2 with Claude 3.5 Sonnet (2024-10-22). See docs/README.md for prompts and details about how this code was generated.
20 
21<a href="https://glama.ai/mcp/servers/zoig549xfd"><img width="380" height="200" src="https://glama.ai/mcp/servers/zoig549xfd/badge" alt="postman-mcp-server MCP server" /></a>
22 
23---
24 
25* [Overview](#overview)
26* [Features](#features)
27  * [Collections](#collections)
28  * [Environments](#environments)
29  * [APIs](#apis)
30  * [Authentication \& Authorization](#authentication--authorization)
31  * [Additional Features](#additional-features)
32* [Installation](#installation)
33  * [Prerequisites](#prerequisites)
34  * [Steps](#steps)
35* [Usage](#usage)
36  * [Setting up API Keys](#setting-up-api-keys)
37  * [Using Claude Desktop](#using-claude-desktop)
38  * [Using Cline](#using-cline)
39  * [Using Zed](#using-zed)
40* [Documentation](#documentation)
41  * [Project Overview](#project-overview)
42* [Rationale](#rationale)
43* [Development](#development)
44* [Debugging](#debugging)
45* [Other MCP Servers](#other-mcp-servers)
46* [License](#license)
47 
48## Overview
49 
50Postman MCP Server is a TypeScript-based MCP server that integrates with the Postman API, providing comprehensive management of Postman collections, environments, and APIs.
51 
52## Features
53 
54### Collections
55- **CRUD Operations**: Create, retrieve, update, and delete Postman collections.
56- **Folder Management**: Organize requests into folders within collections.
57- **Request Management**: Add, update, and delete requests within collections.
58- **Response Management**: Manage responses associated with requests.
59- **Version Control**: Fork, merge, and pull changes for collections.
60- **Comments**: Add and manage comments on collections.
61 
62### Environments
63- **Manage Environments**: Create and retrieve environments for different setups.
64- **CRUD Operations**: Full support for creating, updating, and deleting environments.
65 
66### APIs
67- **API Management**: Create, retrieve, update, and delete APIs.
68- **Schema Support**: Manage API schemas with multi-file support.
69- **Tagging**: Add and manage tags for APIs.
70- **Comments**: Add and manage comments on APIs.
71 
72### Authentication & Authorization
73- **API Key Authentication**: Secure access using API keys.
74- **Role-Based Access Control**: Manage permissions at workspace and collection levels.
75- **Workspace Permissions**: Define permissions specific to workspaces.
76 
77### Additional Features
78- **Private API Network**: Manage elements and folders within a private API network.
79- **Webhooks**: Create webhooks to trigger collections with custom payloads.
80- **Enterprise Features**: Advanced role controls and SCIM support for enterprise environments.
81 
82## Installation
83 
84### Installing via Smithery
85 
86To install Postman MCP Server for Claude Desktop automatically via [Smithery](https://smithery.ai/server/postman-api-server):
87 
88```bash
89npx -y @smithery/cli install postman-api-server --client claude
90```
91 
92### Prerequisites
93- [Node.js](https://nodejs.org/) installed.
94 
95### Steps
96 
971. **Clone the repository:**
98    ```bash
99    git clone https://github.com/delano/postman-api-server.git
100    cd postman-api-server
101    ```
102 
1032. **Install dependencies:**
104    ```bash
105    pnpm install
106    ```
107 
1083. **Build the server:**
109    ```bash
110    pnpm run build
111    ```
112 
1134. **Run in development mode with auto-rebuild:**
114    ```bash
115    pnpm run watch
116    ```
117 
118## Usage
119 
120### Setting up API Keys
121 
1221. **Generate your API Key**
123   - Visit [Postman Account Settings](https://go.postman.co/settings/me/api-keys)
124   - Click "Generate API Key"
125   - Save the key securely - it won't be shown again
126 
1272. **Configure the API Key**
128   - Add the key to your environment as `POSTMAN_API_KEY`
129   - For Claude Desktop or Cline, include it in your config file (see configuration examples below)
130   - Never commit API keys to version control
131 
1323. **Verify Access**
133   - The API key provides access to all Postman resources you have permissions for
134   - Test access by running a simple query (e.g., list workspaces)
135 
136> [!NOTE]
137> If you're using the [Postman API collection](https://www.postman.com/postman/postman-public-workspace/documentation/i2uqzpp/postman-api) directly, store your API key as a `postman-api-key` collection variable.
138 
139### Using Claude Desktop
140 
141To use with Claude Desktop, add the server config:
142 
143- **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
144- **Windows:** `%APPDATA%/Claude/claude_desktop_config.json`
145 
146> [!IMPORTANT]
147> If you're updating this provider, Claude must be restarted to pick up API changes from the input schema (i.e. When the MCP server's ToolDefinition elements have changed). This is because Claude caches the tool definitions when it starts up.
148 
149<img width="480" alt="claude-desktop-settings" src="https://github.com/user-attachments/assets/7ea7cba2-e27e-413a-a50a-590054d51344" />
150 
151#### Example configuration
152 
153```json
154{
155  "mcpServers": {
156    "postman": {
157      "command": "node",
158      "args": [
159        "/path/to/postman-api-server/build/index.js"
160      ],
161      "env": {
162        "POSTMAN_API_KEY": "CHANGEME"
163      }
164    }
165  }
166}
167```
168 
169### Using Cline
170 
171Using the same example configuration, add the server config to your Cline MCP Servers configuration:
172 
173<img width="480" alt="cline-settings" src="https://github.com/user-attachments/assets/651ec517-9aa2-4314-84f5-bee716aa8889" />
174 
175 
176#### Example configuration
177 
178_Same as Claude above._
179 
180### Using Zed
181 
182I'm still trying to get this to work. From the [Zed docs](https://zed.dev/docs/assistant/model-context-protocol) it looks like it needs to be an extension ([also this issue #21455](https://github.com/zed-industries/zed/discussions/21455)).
183 
184---
185 
186## Documentation
187 
188The official [Postman API documentation](https://learning.postman.com/docs/developer/postman-api/intro-api/) is available in the [Postman Public Workspace](https://www.postman.com/postman/postman-public-workspace/).
189 
190### Project Overview
191 
192#### Postman API References & Summaries
193 
194This project leverages the Claude model and Cline extension to convert the OpenAPI specification into TypeScript code, enhancing type safety and integration within the MCP server.
195 
196This GitHub project includes [API References documentation](docs/api/references/README.md) that provides detailed guidance on utilizing the Postman platform programmatically. It covers both the Collection SDK for local development and the Postman API for cloud platform integration. Key topics include authentication mechanisms, rate limits, and in-depth documentation of all API endpoints, including workspaces, collections, environments, mock servers, monitors, and more. Additionally, the guide offers prerequisites and quick-start instructions to facilitate seamless API interactions.
197 
198The `docs/api/summaries` directory contains comprehensive Markdown summaries of the Postman API. These documents outline API endpoints, request/response formats, and implementation details essential for validating and ensuring the functionality of the MCP server. Refer to the [API Summaries README](docs/api/summaries/README.md) for an overview of the documentation structure and implementation strategies.
199 
200#### Converting OpenAPI Spec to TypeScript Code with Claude
201 
202 
203 
204#### Building the MCP Server
205 
206Refer to the [Handlers Documentation](src/handlers/README.md) for detailed specifications on implementing MCP server handlers. This includes URI formats, prompt requirements, and resource handling patterns. This guide is crucial for developers working on integrating and enhancing the Postman API functionalities within the MCP server.
207 
208 
209---
210 
211## Rationale
212 
213The MCP wrapper for Postman tools makes sense primarily as an AI interaction layer for complex, multi-step operations where structure and safety are paramount. However, it may be overengineered for simple operations where direct CLI or API usage would suffice. The MCP wrapper provides most value when:
214 
2151. **Complex Operations**
216- Managing multiple collections
217- Coordinating environments
218- Generating comprehensive reports
219 
2202. **AI-Driven Automation**
221- Automated testing workflows
222- API documentation maintenance
223- Environment management
224 
2253. **Error-Sensitive Operations**
226- Critical API testing
227- Production deployments
228- Compliance checking
229 
230It provides less value for:
231 
2321. **Simple Operations**
233- Basic collection runs
234- Single API calls
235- Quick environment checks
2362. **Direct CLI Usage**
237- Developer-driven operations
238- Local testing
239- Quick iterations
240 
241 
242## Development
243 
244Install dependencies:
245```bash
246pnpm install
247```
248 
249Build the server:
250```bash
251pnpm run build
252```
253 
254For development with auto-rebuild:
255```bash
256pnpm run watch
257```
258 
259## Debugging
260 
261Since MCP servers communicate over stdio, debugging can be challenging. We recommend using the [MCP Inspector](https://github.com/modelcontextprotocol/inspector), available as a package script:
262 
263```bash
264pnpm run inspector
265```
266 
267[Docs](https://modelcontextprotocol.io/docs/tools/inspector)
268 
269The Inspector will provide a URL to access debugging tools in your browser: http://localhost:5173. You will need to add the POSTMAN_API_KEY before connecting. Navigate to "Tools" to get started.
270 
271## Other MCP Servers
272 
273- [Awesome MCP Servers by AppCypher](https://github.com/appcypher/awesome-mcp-servers)
274- [Awesome MCP Servers by PunkPeye](https://github.com/punkpeye/awesome-mcp-servers)
275 
276## License
277 
278This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.
279