postman-mcp
Provides tools for managing Postman collections, environments, mock servers, API specifications, and workspaces through the Postman API.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@postman-mcp list my workspaces"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Postman MCP Server
A production-ready Model Context Protocol (MCP) server that provides 41 Postman API tools for managing collections, environments, mocks, API specifications, and workspaces. Supports Streamable HTTP, SSE, and stdio transports.
Features
š¦ 41 Postman API Tools - Complete Postman API automation
š Multiple Transports - Streamable HTTP, SSE, and stdio support
š Production Ready - Docker support with proper error handling
š Collections - Create, read, update, duplicate collections
š Environments - Manage environment variables
š Mocks - Create and manage mock servers
š API Specs - OpenAPI, AsyncAPI, protobuf, GraphQL support
š¢ Workspaces - Manage team and personal workspaces
š Integration - Sync specs with collections
Available Tools (41)
Collections (7 tools)
createCollection- Create a collection (v2.1.0 format)getCollection- Get collection info (map/minimal/full)getCollections- List workspace collectionsputCollection- Replace collection contentsduplicateCollection- Duplicate to another workspacegetDuplicateCollectionTaskStatus- Check duplication status
Requests & Responses (3 tools)
createCollectionRequest- Create request in collectionupdateCollectionRequest- Update existing requestcreateCollectionResponse- Create request response
Environments (4 tools)
createEnvironment- Create environmentgetEnvironment- Get environment detailsgetEnvironments- List all environmentsputEnvironment- Replace environment contents
Mock Servers (5 tools)
createMock- Create mock servergetMock- Get mock server detailsgetMocks- List all mock serversupdateMock- Update mock serverpublishMock- Publish mock server (set public)
API Specifications (9 tools)
createSpec- Create API spec (OpenAPI/AsyncAPI/protobuf/GraphQL)getSpec- Get spec detailsgetAllSpecs- List workspace specsupdateSpecProperties- Update spec propertiesgetSpecDefinition- Get complete spec definitioncreateSpecFile- Create spec filegetSpecFiles- List all spec filesgetSpecFile- Get file contentsupdateSpecFile- Update spec file
Spec-Collection Integration (4 tools)
generateCollection- Generate collection from specgetSpecCollections- List spec's generated collectionsgenerateSpecFromCollection- Generate spec from collectiongetGeneratedCollectionSpecs- Get collection's generated specssyncCollectionWithSpec- Sync collection with specsyncSpecWithCollection- Sync spec with collection
Workspaces (4 tools)
createWorkspace- Create workspacegetWorkspace- Get workspace detailsgetWorkspaces- List all workspacesupdateWorkspace- Update workspace properties
Other (4 tools)
getAuthenticatedUser- Get current user infogetTaggedEntities- Get entities by tag (Enterprise)runCollection- Run collection with NewmangetEnabledTools- List enabled tools
Quick Start
Prerequisites
Required:
Postman API Key - Get from https://postman.com/settings/me/api-keys
Python 3.10+
Installation
cd postman-tool
# Install in editable mode
pip install -e .
# Verify installation
postman-mcp --helpEnvironment Variables
Required:
export POSTMAN_API_KEY="your_postman_api_key"Windows PowerShell:
$env:POSTMAN_API_KEY = "your_postman_api_key"Run Server
Streamable HTTP (Recommended):
postman-mcp --mode streamable-http --port 8010SSE:
postman-mcp --mode sse --port 8010Stdio (for MCP clients):
postman-mcp --mode stdioDocker
# Build image
docker build -t postman-mcp .
# Run container
docker run -e POSTMAN_API_KEY=your_key -p 8010:8010 postman-mcpMCP Client Configuration
Streamable HTTP
{
"mcpServers": {
"postman": {
"type": "streamable-http",
"url": "http://localhost:8010/mcp"
}
}
}Stdio
{
"mcpServers": {
"postman": {
"command": "postman-mcp",
"args": ["--mode", "stdio"],
"env": {
"POSTMAN_API_KEY": "your_postman_api_key"
}
}
}
}Usage Examples
Get Current User
await call_tool("getAuthenticatedUser", {})List Workspaces
# List my personal workspaces
user = await call_tool("getAuthenticatedUser", {})
workspaces = await call_tool("getWorkspaces", {
"createdBy": user["user"]["id"],
"type": "personal",
"limit": 100
})Create Collection
await call_tool("createCollection", {
"workspace": "workspace-id",
"collection": {
"info": {
"name": "My API Collection",
"description": "Collection for testing",
"schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json"
},
"item": []
}
})Get Collection
# Get lightweight map (default)
await call_tool("getCollection", {
"collectionId": "12345-abc123def456"
})
# Get full payload
await call_tool("getCollection", {
"collectionId": "12345-abc123def456",
"model": "full"
})Create Mock Server
await call_tool("createMock", {
"workspace": "workspace-id",
"mock": {
"name": "My Mock Server",
"collection": "12345-abc123def456", # Collection UID
"environment": "env-id",
"private": false
}
})Create API Specification
await call_tool("createSpec", {
"workspaceId": "workspace-id",
"name": "My API",
"type": "openapi",
"files": [
{
"path": "openapi.yaml",
"content": "openapi: 3.0.0\ninfo:\n title: My API\n version: 1.0.0"
}
]
})Generate Collection from Spec
await call_tool("generateCollection", {
"specId": "spec-id",
"name": "Generated Collection",
"elementType": "collection",
"options": {
"requestParametersResolution": "example",
"exampleParametersResolution": "example"
}
})Create Environment
await call_tool("createEnvironment", {
"workspace": "workspace-id",
"environment": {
"name": "Production",
"values": [
{"key": "base_url", "value": "https://api.example.com", "enabled": true},
{"key": "api_key", "value": "secret", "enabled": true, "type": "secret"}
]
}
})Run Collection
await call_tool("runCollection", {
"collectionId": "12345-abc123def456",
"environmentId": "env-id",
"iterationCount": 1,
"requestTimeout": 30000
})API Endpoints
When running with HTTP transports:
GET /- Server infoGET /health- Health check/mcp/*- MCP protocol endpoints (streamable-http)/sse- SSE endpoint/messages- SSE messages endpoint
Development
Run Tests
pytestProject Structure
postman-tool/
āāā postman_server.py # Main MCP server
āāā tools/
ā āāā toolhandler.py # Base class
ā āāā postman_tools.py # All 41 tool implementations
āāā tests/
ā āāā test_postman.py
āāā pyproject.toml
āāā Dockerfile
āāā README.mdPostman API Details
Authentication
Uses X-Api-Key header with your Postman API key. Get yours at: https://postman.com/settings/me/api-keys
Base URL
https://api.getpostman.comCollection UID Format
Many endpoints require collection UID in format: <OWNER_ID>-<COLLECTION_ID>
To get the UID:
Use
getCollectionand read theuidfieldConstruct from
{ownerId}-{collectionId}where:For team collections:
ownerId = me.teamId(fromgetAuthenticatedUser)For personal collections:
ownerId = me.user.id(fromgetAuthenticatedUser)
Rate Limits
Postman API has rate limits. See: https://learning.postman.com/docs/developer/postman-api/postman-api-rate-limits/
Common Issues
Authentication Error
Error: Postman API error (401)
Solution:
Verify
POSTMAN_API_KEYis set correctlyCheck key is valid at https://postman.com/settings/me/api-keys
Ensure key has required permissions
Collection UID Format
Error: Collection not found
Solution:
Use full UID format:
12345-abc123def456Get UID from
getCollectionresponseFor createMock, pass collection UID, not bare ID
Workspace Required
Error: Workspace is required
Solution:
Call
getWorkspacesto list available workspacesPass
workspacequery parameterFor "my workspaces", call
getAuthenticatedUserfirst
Newman Integration
The runCollection tool requires Newman (Postman's CLI runner) to be integrated programmatically. This is a placeholder that returns instructions.
Requirements
Python 3.10+
Postman API Key
MCP 1.12.0+
httpx, Starlette, Uvicorn
License
MIT License - See LICENSE file for details
Support
For issues, questions, or contributions, please visit the project repository.
Additional Resources
Postman API Documentation: https://learning.postman.com/docs/developer/postman-api/intro-api/
Postman Collection Format: https://schema.postman.com/collection/json/v2.1.0/draft-07/docs/index.html
MCP Protocol: https://modelcontextprotocol.io
Available Tools
41 toolscreateCollectionA
Creates a collection using the Postman Collection v2.1.0 schema format. If workspace is not specified, creates in the oldest personal workspace.
Inputs: workspace, collection.
createCollectionRequestB
Creates a request in a collection. Recommended to pass 'name' property. See Postman Collection Format docs for full properties.
Inputs: collectionId (required), folderId, name, method, +11 more.
createCollectionResponseC
Creates a request response in a collection. Recommended to pass 'name' property. See Response entry in Postman Collection Format docs.
Inputs: collectionId (required), request (required), name, description, +15 more.
createEnvironmentB
Creates an environment. Max size 30MB. If workspace not specified, creates in oldest personal workspace.
Inputs: workspace, environment.
createMockA
Creates a mock server for a collection. Use collection UID (ownerId-collectionId). Use workspace param to specify target workspace.
Inputs: workspace, mock.
createSpecA
Creates an API spec in Postman's Spec Hub. Supports OpenAPI 2.0/3.0/3.1, AsyncAPI 2.0, protobuf 2/3, GraphQL. Max file size 10MB.
Inputs: files (required), name (required), type (required), workspaceId (required).
createSpecFileA
Creates an API spec file. Use '/' in path to create folders. File assigned DEFAULT type. Max size 10MB.
Inputs: specId (required), content (required), path (required).
createWorkspaceA
Creates a new workspace. Private/Partner workspaces require Team/Enterprise. Public names must be unique. Pass teamId if Organizations is enabled.
Inputs: workspace.
duplicateCollectionB
Duplicates a collection to another workspace. Returns a task ID - use getDuplicateCollectionTaskStatus to check status.
Inputs: collectionId (required), workspace (required), suffix.
generateCollectionA
Creates a collection from an API spec. Returns polling link to task status.
Inputs: specId (required), name (required), elementType (required), options.
generateSpecFromCollectionB
Generates an API spec for a collection. Returns polling link to task status.
Inputs: collectionUid (required), name (required), elementType (required), format (required), +1 more.
getAllSpecsC
Gets all API specifications in a workspace.
Inputs: workspaceId (required), cursor, limit.
getAuthenticatedUserA
Gets information about the authenticated user. Use this to get current user context (user.id, username, teamId, roles) for 'my ...' requests.
Inputs: no named parameters.
getCollectionA
Get information about a collection. Returns lightweight collection map by default. Use model='minimal' for root-level IDs only, or model='full' for complete payload.
Inputs: collectionId (required), access_key, model.
getCollectionsA
Gets all collections in a workspace. Workspace ID is required - ask user if not provided.
Inputs: workspace (required), limit, name, offset.
getDuplicateCollectionTaskStatusC
Gets the status of a collection duplication task.
Inputs: taskId (required).
getEnabledToolsA
IMPORTANT: Run this first when a requested tool is unavailable. Returns info about enabled tools in full and minimal sets.
Inputs: no named parameters.
getEnvironmentC
Gets information about an environment.
Inputs: environmentId (required).
getEnvironmentsB
Gets all environments. Optionally filter by workspace.
Inputs: workspace.
getGeneratedCollectionSpecsC
Gets the API spec generated for a collection.
Inputs: collectionUid (required), elementType (required).
getMockB
Gets information about a mock server, including associated collection UID and mockUrl.
Inputs: mockId (required).
getMocksA
Gets all active mock servers. Always pass workspace or teamId. Prefer workspace when known. Set teamId from GET /me (me.teamId) for team scope.
Inputs: teamId, workspace.
getSpecC
Gets information about an API specification.
Inputs: specId (required).
getSpecCollectionsB
Gets all collections generated from an API spec.
Inputs: specId (required), elementType (required), cursor, limit.
getSpecDefinitionB
Gets the complete contents of an API spec's definition.
Inputs: specId (required).
getSpecFileB
Gets the contents of an API spec's file.
Inputs: specId (required), filePath (required).
getSpecFilesC
Gets all files in an API specification.
Inputs: specId (required).
getTaggedEntitiesB
Gets Postman entities by tag. Enterprise only - returns 404 on Free/Basic/Professional plans.
Inputs: slug (required), cursor, direction, entityType, +1 more.
getWorkspaceB
Gets information about a workspace (visibility: personal/team/private/public/partner).
Inputs: workspaceId (required), include.
getWorkspacesA
Gets all accessible workspaces. For 'my ...' requests, call GET /me first and pass createdBy={me.user.id}. Paginated with cursor.
Inputs: createdBy, type, cursor, elementId, +3 more.
publishMockA
Publishes a mock server (sets Access Control to public).
Inputs: mockId (required).
putCollectionA
Replaces collection contents using Postman Collection v2.1.0 format. Include ID values or they'll be removed and recreated. Max size 100MB.
Inputs: collectionId (required), Prefer, collection.
putEnvironmentA
Replaces all environment contents. Max size 30MB.
Inputs: environmentId (required), environment.
runCollectionB
Runs a Postman collection with detailed test results and execution statistics. Supports optional environment for variable substitution.
Inputs: collectionId (required), environmentId, iterationCount, requestTimeout, +5 more.
syncCollectionWithSpecA
Syncs a collection generated from an API spec. Async endpoint returns 202. Only for OpenAPI 2.0/3.0/3.1.
Inputs: specId (required), collectionUid (required).
syncSpecWithCollectionB
Syncs an API spec linked to a collection. Async endpoint returns 202. Only for OpenAPI 2.0/3.0/3.1.
Inputs: specId (required), collectionUid (required).
updateCollectionRequestA
Updates a request in a collection (PATCH-like: only updates provided fields). Cannot change folder. Use collection ID (not UID).
Inputs: collectionId (required), requestId (required), name, method, +11 more.
updateMockA
Updates a mock server (name, environment, privacy, default response).
Inputs: mockId (required), mock.
updateSpecFileA
Updates an API spec's file. Only pass one property at a time (content, name, or type). Max size 10MB.
Inputs: specId (required), filePath (required), content, name, +1 more.
updateSpecPropertiesB
Updates an API spec's properties (e.g., name).
Inputs: specId (required), name (required).
updateWorkspaceA
Updates a workspace property (name, visibility, etc.). Some visibility changes not allowed. Public names must be unique.
Inputs: workspaceId (required), workspace.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelogā¦
TDQS
Scored across 41 tools
Most tools have distinct purposes, e.g., createCollection vs generateCollection, but some pairs like syncCollectionWithSpec and generateCollection could be confused without careful reading. Overall clear.
All tools use consistent camelCase naming with a clear verb-noun pattern (e.g., createCollection, getEnvironment). No mixing of conventions.
41 tools is on the higher side for an MCP server, but the domain (Postman API) is broad and justifies many operations. However, it slightly exceeds the typical range.
The tool set lacks delete operations for collections, environments, mocks, and specs, creating significant gaps in lifecycle management. Also, collection update is limited to full replacement.
Related MCP Connectors
MCP server for AI access to SmartBear tools, including BugSnag, Reflect, Swagger, PactFlow, QTM4J.
MCP server for AI access to Swagger by SmartBear.
Nifty's MCP server ā exposes tasks, projects, messages, and files as tools for AI agents.
The official MCP Server from Mia-Platform to interact with Mia-Platform Console