postman-mcp
Provides tools for interacting with the Postman API, enabling management of collections, environments, and APIs, including CRUD operations, folder organization, and version control features like forking and merging.
Postman MCP Server
Version: v0.2.0
An MCP server that provides access to the Postman API. Functionality is based on the official OpenAPI specification. For more information, see the Postman API documentation.
This project is part of the Model Context Protocol (MCP) initiative from Anthropic. For more information, visit the MCP GitHub repository and the announcement on the Anthropic blog.
Skip ahead to install instructions
This project is currently under active development. Please use with caution and expect breaking changes.
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.
Overview
Postman MCP Server is a TypeScript-based MCP server that integrates with the Postman API, providing comprehensive management of Postman collections, environments, and APIs.
Related MCP server: mcp-untun
Features
Collections
CRUD Operations: Create, retrieve, and update Postman collections.
Folder Management: Organize requests into folders within collections.
Request Management: Add and update requests within collections.
Response Management: Manage responses associated with requests.
Version Control: Fork, merge, and pull changes for collections.
Comments: Add and manage comments on collections.
Environments
Manage Environments: Create and retrieve environments for different setups.
CRUD Operations: Full support for creating, updating, and deleting environments.
APIs
API Management: Create, retrieve, update, and delete APIs.
Schema Support: Manage API schemas with multi-file support.
Tagging: Add and manage tags for APIs.
Comments: Add and manage comments on APIs.
Authentication & Authorization
API Key Authentication: Secure access using API keys.
Role-Based Access Control: Manage permissions at workspace and collection levels.
Workspace Permissions: Define permissions specific to workspaces.
Additional Features
Private API Network: Manage elements and folders within a private API network.
Webhooks: Create webhooks to trigger collections with custom payloads.
Enterprise Features: Advanced role controls and SCIM support for enterprise environments.
Installation
Installing via npm (Recommended)
Install the package globally:
npm install -g @postmanv3/postman-mcp-serverOr install locally in your project:
npm install @postmanv3/postman-mcp-serverInstalling via Smithery
To install Postman MCP Server for Claude Desktop automatically via Smithery:
npx -y @smithery/cli install postman-api-server --client claudeInstalling from Source
If you prefer to build from source:
Clone the repository:
git clone https://github.com/PostmanV3/postman-mcp-server.git cd postman-mcp-serverInstall dependencies:
npm install # or pnpm installBuild the server:
npm run build # or pnpm run buildRun in development mode with auto-rebuild:
npm run watch # or pnpm run watch
Usage
Setting up API Keys
Generate your API Key
Visit Postman Account Settings
Click "Generate API Key"
Save the key securely - it won't be shown again
Configure the API Key
Add the key to your environment as
POSTMAN_API_KEYFor Claude Desktop or Cline, include it in your config file (see configuration examples below)
Never commit API keys to version control
Verify Access
The API key provides access to all Postman resources you have permissions for
Test access by running a simple query (e.g., list workspaces)
If you're using thePostman API collection directly, store your API key as a postman-api-key collection variable.
Using Claude Desktop
To use with Claude Desktop, add the server config:
macOS:
~/Library/Application Support/Claude/claude_desktop_config.jsonWindows:
%APPDATA%/Claude/claude_desktop_config.json
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.
Example configuration
Recommended: Using npx (works with both global and local installations):
{
"mcpServers": {
"postman": {
"command": "npx",
"args": [
"-y",
"@postmanv3/postman-mcp-server"
],
"env": {
"POSTMAN_API_KEY": "CHANGEME"
}
}
}
}Alternative: Direct path (if installed locally):
{
"mcpServers": {
"postman": {
"command": "node",
"args": [
"./node_modules/@postmanv3/postman-mcp-server/build/index.js"
],
"env": {
"POSTMAN_API_KEY": "CHANGEME"
}
}
}
}Alternative: Global installation path (typical paths - find yours with npm root -g):
{
"mcpServers": {
"postman": {
"command": "node",
"args": [
"/usr/local/lib/node_modules/@postmanv3/postman-mcp-server/build/index.js"
],
"env": {
"POSTMAN_API_KEY": "CHANGEME"
}
}
}
}To find your global node_modules path, runnpm root -g and replace the path above accordingly.
Thenpx approach is recommended as it automatically finds the package whether it's installed globally or locally, and handles updates automatically.
Using Cline
Using the same example configuration, add the server config to your Cline MCP Servers configuration:
Example configuration
Same as Claude above.
Using Zed
I'm still trying to get this to work. From the Zed docs it looks like it needs to be an extension (also this issue #21455).
Documentation
The official Postman API documentation is available in the Postman Public Workspace.
Project Overview
Postman API References & Summaries
This 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.
This GitHub project includes API References documentation 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, and more. Additionally, the guide offers prerequisites and quick-start instructions to facilitate seamless API interactions.
The 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 for an overview of the documentation structure and implementation strategies.
Converting OpenAPI Spec to TypeScript Code with Claude
Building the MCP Server
Refer to the Handlers Documentation 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.
Rationale
The 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:
Complex Operations
Managing multiple collections
Coordinating environments
Generating comprehensive reports
AI-Driven Automation
Automated testing workflows
API documentation maintenance
Environment management
Error-Sensitive Operations
Critical API testing
Production deployments
Compliance checking
It provides less value for:
Simple Operations
Basic collection runs
Single API calls
Quick environment checks
Direct CLI Usage
Developer-driven operations
Local testing
Quick iterations
Development
Install dependencies:
npm install
# or
pnpm installBuild the server:
npm run build
# or
pnpm run buildFor development with auto-rebuild:
npm run watch
# or
pnpm run watchDebugging
Since MCP servers communicate over stdio, debugging can be challenging. We recommend using the MCP Inspector, available as a package script:
npm run inspector
# or
pnpm run inspectorThe 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.
Other MCP Servers
License
This project is licensed under the MIT License. See the LICENSE file for details.
This MCP server is for research purposes only. Any data collection or monitoring will be conducted solely for security research purposes.
Available Tools
77 toolsadd_api_collectionC
Add a collection to an API
Inputs: apiId (required), operationType (required), data.
add_pan_elementB
Add element or folder to Private API Network
Inputs: type (required), name (required), description, summary, +2 more.
create_apiC
Create a new API
Inputs: name (required), workspaceId (required), summary, description.
create_api_commentB
Create a new comment on an API (max 10,000 characters)
Inputs: apiId (required), content (required), threadId.
create_api_schemaC
Create a schema for an API
Inputs: apiId (required), type (required), files (required).
create_api_versionB
Create a new version of an API
Inputs: apiId (required), name (required), schemas (required), collections (required), +2 more.
create_collectionB
Create a new collection in a workspace. Supports Postman Collection v2.1.0 format.
Inputs: collection (required), workspace.
create_collection_folderB
Create a new folder in a collection
Inputs: collection_id (required), folder (required).
create_collection_requestB
Create a new request in a collection
Inputs: collection_id (required), request (required), folder_id.
create_collection_responseC
Create a new response in a collection
Inputs: collection_id (required), request_id (required), response (required).
create_environmentB
Create a new environment in a workspace. Creates in "My Workspace" if workspace not specified.
Inputs: environment (required), workspace.
create_update_schema_fileC
Create or update a schema file
Inputs: apiId (required), schemaId (required), filePath (required), content (required), +1 more.
create_webhookB
Creates webhook that triggers collection with custom payload
Inputs: workspace (required), webhook (required).
delete_apiB
Delete an API
Inputs: apiId (required).
delete_api_commentC
Delete an API comment
Inputs: apiId (required), commentId (required).
delete_api_versionC
Delete an API version
Inputs: apiId (required), versionId (required).
delete_collection_access_keyD
Delete a collection access key
Inputs: keyId (required).
delete_environmentB
Delete an environment
Inputs: environmentId (required).
delete_schema_fileB
Delete a schema file
Inputs: apiId (required), schemaId (required), filePath (required).
fork_collectionB
Fork a collection to a workspace
Inputs: collection_id (required), workspace (required), label (required).
fork_environmentB
Create a fork of an environment in a workspace
Inputs: environmentId (required), label (required), workspace (required).
get_accountsB
Gets Postman billing account details for the given team
Inputs: no named parameters.
get_apiC
Get details of a specific API
Inputs: apiId (required), include.
get_api_collectionC
Get a specific collection from an API
Inputs: apiId (required), collectionId (required), versionId.
get_api_commentsB
Get comments for an API
Inputs: apiId (required), cursor, limit.
get_api_schemaC
Get a specific schema from an API
Inputs: apiId (required), schemaId (required), versionId, bundled.
get_api_schema_filesC
Get files in an API schema
Inputs: apiId (required), schemaId (required), cursor, limit, +1 more.
get_api_tagsB
Get tags for an API
Inputs: apiId (required).
get_api_versionB
Get a specific version of an API
Inputs: apiId (required), versionId (required).
get_api_versionsC
Get all versions of an API
Inputs: apiId (required), cursor, limit.
get_authenticated_userB
Get authenticated user information
Inputs: no named parameters.
get_collectionC
Get details of a specific collection
Inputs: collection_id (required), access_key, model.
get_collection_folderC
Get details of a specific folder in a collection
Inputs: collection_id (required), folder_id (required), ids, uid, +1 more.
get_collection_forksB
Get a list of collection forks
Inputs: collection_id (required), cursor, limit, direction, +1 more.
get_collection_requestB
Get details of a specific request in a collection
Inputs: collection_id (required), request_id (required), ids, uid, +1 more.
get_collection_responseB
Get details of a specific response in a collection
Inputs: collection_id (required), response_id (required), ids, uid, +1 more.
get_collection_rolesC
Get roles for a collection
Inputs: collectionId (required).
get_environmentB
Get details of a specific environment
Inputs: environmentId (required).
get_environment_forksB
Get a list of environment forks
Inputs: environmentId (required), cursor, direction, limit, +1 more.
get_schema_file_contentsC
Get contents of a schema file
Inputs: apiId (required), schemaId (required), filePath (required), versionId.
get_tagged_elementsC
Get elements by tag
Inputs: slug (required), limit, direction, cursor, +1 more.
get_task_statusC
Get status of an asynchronous task
Inputs: apiId (required), taskId (required).
get_user_infoB
Get information about the authenticated user
Inputs: no named parameters.
get_workspaceB
Get details of a specific workspace
Inputs: workspace (required), include.
get_workspace_rolesC
Get roles for a specific workspace
Inputs: workspaceId (required), includeScim.
get_workspace_tagsC
Get workspace tags
Inputs: workspaceId (required).
health_checkA
Perform a local system health check to verify Postman MCP server configuration and connectivity. Returns system information and configuration status.
Inputs: no named parameters.
list_account_invoicesB
Gets all invoices for a Postman billing account filtered by status
Inputs: accountId (required), status (required).
list_apisC
List all APIs in a workspace
Inputs: workspaceId (required), createdBy, cursor, description, +1 more.
list_collection_access_keysB
List collection access keys with optional filtering by collection ID
Inputs: collectionId, cursor.
list_collectionsA
List all collections in a workspace. Supports filtering and pagination.
Inputs: workspace, name, limit, offset.
list_environmentsB
List all environments in a workspace. If workspace not specified, lists environments in "My Workspace".
Inputs: workspace.
list_pan_elementsC
Get all elements and folders in Private API Network
Inputs: since, until, addedBy, name, +8 more.
list_workspace_rolesA
Get all available workspace roles based on team's plan
Inputs: no named parameters.
list_workspacesC
List all workspaces
Inputs: type, createdBy, include.
merge_collection_forkB
Merge a forked collection back into its parent
Inputs: source (required), destination (required), strategy (required).
merge_environment_forkB
Merge a forked environment back into its parent
Inputs: environmentId (required), source (required), destination (required), strategy.
patch_collectionA
Partially update a collection. Only updates provided fields.
Inputs: collection_id (required), collection (required).
pull_collection_changesB
Pull changes from parent collection into forked collection
Inputs: collection_id (required).
pull_environmentB
Pull changes from parent environment into forked environment
Inputs: environmentId (required), source (required), destination (required).
remove_pan_elementB
Remove element or folder from Private API Network
Inputs: elementId (required), elementType (required).
resolve_comment_threadB
Resolves a comment and any associated replies
Inputs: threadId (required).
sync_collection_with_schemaC
Sync a collection with its schema
Inputs: apiId (required), collectionId (required).
transfer_collection_itemsC
Transfer items between collections
Inputs: type (required), ids (required), target (required), mode (required), +1 more.
update_apiC
Update an existing API
Inputs: apiId (required), name, summary, description.
update_api_commentB
Update an existing API comment (max 10,000 characters)
Inputs: apiId (required), commentId (required), content (required).
update_api_tagsB
Update tags for an API
Inputs: apiId (required), tags (required).
update_api_versionC
Update an API version
Inputs: apiId (required), versionId (required), name (required), releaseNotes.
update_collectionA
Update an existing collection. Full collection replacement with maximum size of 20 MB.
Inputs: collection_id (required), collection (required).
update_collection_folderA
Update a folder in a collection. Acts like PATCH, only updates provided values.
Inputs: collection_id (required), folder_id (required), folder (required).
update_collection_requestA
Update a request in a collection. Cannot change request folder.
Inputs: collection_id (required), request_id (required), request (required).
update_collection_responseA
Update a response in a collection. Acts like PATCH, only updates provided values.
Inputs: collection_id (required), response_id (required), response (required).
update_collection_rolesB
Update collection roles (requires EDITOR role)
Inputs: collectionId (required), operations (required).
update_environmentA
Update an existing environment. Only include variables that need to be modified.
Inputs: environmentId (required), environment (required).
update_pan_elementC
Update element or folder in Private API Network
Inputs: elementId (required), elementType (required), name, description, +2 more.
update_workspace_rolesB
Update workspace roles for users and groups (limited to 50 operations per call)
Inputs: workspaceId (required), operations (required), identifierType.
update_workspace_tagsD
Update workspace tags
Inputs: workspaceId (required), tags (required).
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 77 tools
Most tools have distinct purposes targeting specific resources and actions, such as create_api vs. update_api or get_collection vs. list_collections. However, some overlap exists, like get_authenticated_user and get_user_info, which could cause confusion despite slight differences in scope. Overall, the toolset is well-organized with clear boundaries for the majority of operations.
Tool names follow a highly consistent verb_noun pattern throughout, such as create_api, get_api, update_api, and delete_api. This consistency extends across all resources like collections, environments, and workspaces, making the toolset predictable and easy to navigate. Minor deviations like health_check or get_tagged_elements still adhere to the overall naming convention.
With 77 tools, the count is excessive for typical MCP server purposes, making it overwhelming and difficult for agents to manage efficiently. While Postman's API is feature-rich, this many tools suggests poor scoping or unnecessary granularity, such as separate tools for every minor operation like get_collection_folder and get_collection_request. A more consolidated approach would improve usability.
The toolset provides comprehensive CRUD and lifecycle coverage for Postman's domain, including APIs, collections, environments, workspaces, and related features like comments, forks, and webhooks. It supports all essential operations from creation to deletion, with no apparent gaps that would hinder agent workflows. The inclusion of niche tools like sync_collection_with_schema and health_check further enhances completeness.
Related MCP Connectors
Related MCP Servers
- MIT
- -
- -
- AlicenseNot gradedqualityDmaintenanceAn MCP server that converts Postman API requests into executable tools for LLMs using the Postman Runtime. It supports complex authentication types and enables seamless integration between Postman collections and MCP clients like Claude Desktop.MIT