Skip to main content
Glama

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 collections

  • putCollection - Replace collection contents

  • duplicateCollection - Duplicate to another workspace

  • getDuplicateCollectionTaskStatus - Check duplication status

Requests & Responses (3 tools)

  • createCollectionRequest - Create request in collection

  • updateCollectionRequest - Update existing request

  • createCollectionResponse - Create request response

Environments (4 tools)

  • createEnvironment - Create environment

  • getEnvironment - Get environment details

  • getEnvironments - List all environments

  • putEnvironment - Replace environment contents

Mock Servers (5 tools)

  • createMock - Create mock server

  • getMock - Get mock server details

  • getMocks - List all mock servers

  • updateMock - Update mock server

  • publishMock - Publish mock server (set public)

API Specifications (9 tools)

  • createSpec - Create API spec (OpenAPI/AsyncAPI/protobuf/GraphQL)

  • getSpec - Get spec details

  • getAllSpecs - List workspace specs

  • updateSpecProperties - Update spec properties

  • getSpecDefinition - Get complete spec definition

  • createSpecFile - Create spec file

  • getSpecFiles - List all spec files

  • getSpecFile - Get file contents

  • updateSpecFile - Update spec file

Spec-Collection Integration (4 tools)

  • generateCollection - Generate collection from spec

  • getSpecCollections - List spec's generated collections

  • generateSpecFromCollection - Generate spec from collection

  • getGeneratedCollectionSpecs - Get collection's generated specs

  • syncCollectionWithSpec - Sync collection with spec

  • syncSpecWithCollection - Sync spec with collection

Workspaces (4 tools)

  • createWorkspace - Create workspace

  • getWorkspace - Get workspace details

  • getWorkspaces - List all workspaces

  • updateWorkspace - Update workspace properties

Other (4 tools)

  • getAuthenticatedUser - Get current user info

  • getTaggedEntities - Get entities by tag (Enterprise)

  • runCollection - Run collection with Newman

  • getEnabledTools - List enabled tools

Quick Start

Prerequisites

Required:

  1. Postman API Key - Get from https://postman.com/settings/me/api-keys

  2. Python 3.10+

Installation

cd postman-tool

# Install in editable mode
pip install -e .

# Verify installation
postman-mcp --help

Environment 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 8010

SSE:

postman-mcp --mode sse --port 8010

Stdio (for MCP clients):

postman-mcp --mode stdio

Docker

# Build image
docker build -t postman-mcp .

# Run container
docker run -e POSTMAN_API_KEY=your_key -p 8010:8010 postman-mcp

MCP 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 info

  • GET /health - Health check

  • /mcp/* - MCP protocol endpoints (streamable-http)

  • /sse - SSE endpoint

  • /messages - SSE messages endpoint

Development

Run Tests

pytest

Project 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.md

Postman 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.com

Collection UID Format

Many endpoints require collection UID in format: <OWNER_ID>-<COLLECTION_ID>

To get the UID:

  1. Use getCollection and read the uid field

  2. Construct from {ownerId}-{collectionId} where:

    • For team collections: ownerId = me.teamId (from getAuthenticatedUser)

    • For personal collections: ownerId = me.user.id (from getAuthenticatedUser)

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:

Collection UID Format

Error: Collection not found

Solution:

  • Use full UID format: 12345-abc123def456

  • Get UID from getCollection response

  • For createMock, pass collection UID, not bare ID

Workspace Required

Error: Workspace is required

Solution:

  • Call getWorkspaces to list available workspaces

  • Pass workspace query parameter

  • For "my workspaces", call getAuthenticatedUser first

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

Available Tools

41 tools
createCollectionA

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

    B3.2/5.0

    Scored across 41 tools

    Disambiguation4/5

    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.

    Naming Consistency5/5

    All tools use consistent camelCase naming with a clear verb-noun pattern (e.g., createCollection, getEnvironment). No mixing of conventions.

    Tool Count3/5

    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.

    Completeness2/5

    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