DOCSEARCHbyAlgolia
Submit Docs

Postman MCP Server

repository·main·Indexed 42 days ago

https://github.com/postmanlabs/postman-mcp-server

A Model Context Protocol (MCP) server that connects AI agents like Claude, Cursor, and Copilot to Postman workspaces, collections, and environments. Version 2.12.3 supports remote and local setups with four tool configurations: Minimal, Code, Full, and Learn. It enables automated API testing, management, and code generation via the Postman API, supporting both US and EU regions with OAuth or API key authentication.

Tokens
10.9K
Snippets
31
Records
44
Agent score
55%

What's inside Postman MCP Server

  1. Authentication for Postman MCP Server

    main

    Authentication methods depend on whether you are using the Remote, EU, or Local server:

    • Remote Server (https://mcp.postman.com): Supports OAuth, which is fully compliant with the MCP Authorization specification and requires no manual API key configuration.
    • EU Remote Server: Supports only Postman API key authentication. OAuth is not supported.
    • Local Server: Supports only Postman API key authentication via the POSTMAN_API_KEY environment variable.

  2. Configure Postman MCP Server tool modes

    main

    The Postman MCP Server provides four distinct tool configurations to tailor the capabilities provided to your AI agent:

    • Minimal (Default): Includes essential tools for basic Postman operations like managing collections, workspaces, or environments.
    • Code: Includes tools to generate high-quality, well-organized client code from public and internal API definitions. Best for consuming APIs.
    • Full: Includes all 100+ available Postman API tools. Best for advanced collaboration and Enterprise features.
    • Learn: Searches Postman Docs for guides, tutorials, and reference content. Best for agents needing to discover Postman features or API concepts.

  3. Understand Postman MCP Server core concepts

    main

    The Postman MCP Server is a Model Context Protocol (MCP) server that exposes Postman's API as a set of tools. It allows you to interact with a Postman workspace programmatically to manage collections, environments, APIs, mocks, monitors, and more.

    Key Postman Elements

    • Workspace: A shared space grouping related collections, environments, APIs, mocks, and monitors.
    • Collection: An ordered set of API requests grouped into folders. The primary unit for organizing and running API calls.
    • Folder: A logical, nestable grouping of requests inside a collection.
    • Request: A single API call definition (method, URL, headers, body, etc.).
    • Response (saved example): A snapshot of a request/response pair used by mock servers and for documentation.
    • Environment: A set of key-value variables (types: default or secret) used to switch contexts (e.g., dev vs. prod).
    • API (Spec): A versioned API definition (OpenAPI, GraphQL, etc.).
    • Mock server: A simulated endpoint that returns responses based on saved examples.
    • Monitor: A scheduled runner that executes a collection at intervals for uptime or integration testing.
    • Tags: Labels for categorization and search.

  4. Access Postman MCP Server documentation and setup guides

    main

    To get started with the Postman MCP Server, use the following resources:

    • General Overview: For installation, client configuration, and a list of available tools, refer to the Postman MCP Server overview.
    • Client Setup: For specific instructions on setting up MCP clients like Claude, Cursor, or VS Code, see the README.
    • Docker Deployment: For instructions on running the server via Docker, see DOCKER.md.
    • Testing Tools: You can manually exercise the server's capabilities by connecting to the local or remote server and using the Postman MCP Server collection.

  5. Navigate a collection after discovery

    main

    Once you have identified a collection via search, do not use searchPostmanElements to find its contents. Instead, use the following navigation tools:

    1. getCollection(collectionId): Fetch the full collection details, including the recursive itemRefs index.
    2. getCollectionRequest(requestId, collectionId, uid: true, populate: false): Explore a specific request within the collection.
    3. getCollectionFolder(folderId, collectionId, uid: true, populate: false): Explore a specific folder within the collection.

    Note: Always use uid: true when navigating specific items to ensure precision.

  6. Configure the Postman MCP Server for the EU region

    main

    If you require support for the EU region, use the following configurations:

    Remote EU Server

    Use these URLs for streamable HTTP:

    • Full: https://mcp.eu.postman.com/mcp
    • Code: https://mcp.eu.postman.com/code
    • Minimal: https://mcp.eu.postman.com/minimal

    Note: The EU remote server only supports API key authentication; OAuth is not supported.

    Local EU Server

    For the STDIO public package, you can specify the region in two ways:

    1. Use the --region eu flag.
    2. Set the POSTMAN_API_BASE_URL environment variable directly.
    # Example using flag for local EU setup
npx @postman/postman-mcp-server --region eu

  7. Run the Postman MCP Server using Docker

    main

    You can run the Postman MCP Server directly using a pre-built image. This method allows Docker to automatically discover, download, and run the image. You must provide your Postman API key via the POSTMAN_API_KEY environment variable.

    Use the following command to start the server:

    docker run -i -e POSTMAN_API_KEY="<your-secret-key>" mcp/postman

  8. Build and run the Postman MCP Server from source in Docker

    main

    If you prefer to build the image manually, follow these steps:

    1. Build the image: Run the build command to create a local image tagged postman-api-mcp-stdio.
    2. Run the container: Use one of the following modes, ensuring you replace <your-secret-key> with your actual Postman API key.

    Minimal Mode: Runs the server with standard configuration.

    Full Mode: Runs the server with the --full flag enabled.

    # Build
docker build -t postman-api-mcp-stdio .

# Run Minimal
docker run -i -e POSTMAN_API_KEY="<your-secret-key>" postman-api-mcp-stdio

# Run Full
docker run -i -e POSTMAN_API_KEY="<your-secret-key>" postman-api-mcp-stdio --full
    docker build -t postman-api-mcp-stdio .
docker run -i -e POSTMAN_API_KEY="<your-secret-key>" postman-api-mcp-stdio

  9. Quick start: Connect to the Postman MCP Server

    main

    You can connect to the Postman MCP Server using either a Remote or Local setup depending on your needs.

    Remote Setup

    Use the remote server for the best developer experience with OAuth support. Add the appropriate URL to your MCP host's configuration based on the desired tool configuration:

    • Minimal: https://mcp.postman.com/minimal (Default: basic Postman operations)
    • Code: https://mcp.postman.com/code (API client code generation)
    • Full: https://mcp.postman.com/mcp (All 100+ Postman API tools)

    Note: For EU or API key authentication, pass Authorization: Bearer <POSTMAN_API_KEY> as a header.

    Local Setup

    Run the server locally using npx. This is ideal for testing local APIs that the remote server cannot access. You must set the POSTMAN_API_KEY environment variable.

    Use the following flags to select the tool configuration:

    • --code for Code mode
    • --full for Full mode
    # Remote (add to MCP host config)
https://mcp.postman.com/minimal

# Local
npx @postman/postman-mcp-server

  10. Explore and test with the Postman MCP Server collection

    main

    The Postman MCP Server collection is a public collection used to explore, test, and connect to the server. It allows you to:

    • Browse the complete list of available tools.
    • Test the Remote server (Full and Minimal versions).
    • Test the Local server.

  11. Get help with setup, workflows, or Postman account issues

    main

    Depending on your question, use the appropriate channel:

    • Setup, MCP Clients, or Workflows: For "how do I..." questions, visit the Postman Community for the fastest response.
    • Postman Account, Billing, or Postman API: These are not managed in this repository. Contact Postman support directly.
    • Security Vulnerabilities: Do not open a public issue for suspected vulnerabilities. Follow the instructions in SECURITY.md.

  12. Report bugs, tool requests, or documentation issues

    main

    If you encounter issues or want to request new features, use the following GitHub issue templates to ensure your report is actionable: