Postman MCP

A Model Context Protocol (MCP) server that provides seamless integration with the Postman API. This package enables AI assistants and applications to interact with Postman workspaces, collections, requests, environments, and folders programmatically.

🚀 Features

📁 Workspace Management

List all workspaces
Get detailed workspace information
Create new workspaces (personal/team)
Update workspace metadata

📚 Collection Management

List collections within workspaces
Get collection details with full structure
Create new collections
Update collection metadata and variables
Delete collections

🔧 Request Management

Add new HTTP requests to collections
Update existing requests (method, URL, headers, body)
Move requests between folders
Delete requests
Support for all HTTP methods (GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS)

🌍 Environment Management

List environments in workspaces
Get environment details and variables
Create new environments with variables
Update environment variables
Delete environments
Support for secret, default, and custom variable types

📂 Folder Organization

Create nested folder structures
Organize requests within folders
Support for hierarchical folder paths

⚙️ Setup

1. Get Your Postman API Key

Go to Postman Account Settings
Click "Generate API Key"
Give it a name and copy the generated key

2. MCP Configuration

For Claude Desktop

Add to your Claude Desktop configuration file (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "postman": {
      "command": "npx",
      "args": ["postman-mcp"],
      "env": {
        "POSTMAN_API_KEY": "your_postman_api_key_here"
      }
    }
  }
}

For Cursor

Add the configuration to your Cursor settings:

{
  "mcp": {
    "servers": {
      "postman": {
        "command": "npx postman-mcp",
        "env": {
          "POSTMAN_API_KEY": "your_postman_api_key_here"
        }
      }
    }
  }
}

For Warp

Add the following to your Warp session setup:

{
  "postman": {
    "command": "npx",
    "args": ["postman-mcp"],
    "env": {
      "POSTMAN_API_KEY": "your_postman_api_key_here"
    },
    "working_directory": null,
    "start_on_launch": true
  }
}

For Other MCP Clients

Use the standard MCP server connection with:

Command: npx postman-mcp or node path/to/postman-mcp/dist/index.js
Transport: stdio
Environment: Set POSTMAN_API_KEY

🛠️ Development Setup

Prerequisites

Node.js 18+
npm or yarn
Postman API key

Local Development

Clone the repository:

git clone https://github.com/SalehKhatri/postman-mcp.git
cd postman-mcp

Install dependencies:
```
npm install
```

Set up environment:

cp .env.example .env
# Edit .env and add your POSTMAN_API_KEY

Build the project:
```
npm run build
```
Run in development mode:
```
npm run dev
```

🔍 Available Tools

Workspace Operations

list_workspaces - Get all workspaces
get_workspace - Get workspace details
create_workspace - Create new workspace
update_workspace - Update workspace info

Collection Operations

list_collections - Get collections in workspace
get_collection - Get full collection structure
create_collection - Create new collection
update_collection - Update collection metadata
delete_collection - Remove collection

Request Operations

add_request - Add HTTP request to collection
update_request - Modify existing request
delete_request - Remove request from collection

Environment Operations

list_environments - Get environments in workspace
get_environment - Get environment variables
create_environment - Create new environment
update_environment - Modify environment variables
delete_environment - Remove environment

Folder Operations

create_folder - Create folder in collection

💡 Usage Examples

Basic Workflow

// List all workspaces
const workspaces = await mcp.callTool("list_workspaces", {});

// Get collections in a workspace
const collections = await mcp.callTool("list_collections", {
  workspaceId: "workspace-id",
});

// Create a new request
await mcp.callTool("add_request", {
  collectionUid: "collection-uid",
  name: "Get Users",
  method: "GET",
  url: "https://api.example.com/users",
  headers: {
    "Content-Type": "application/json",
    Authorization: "Bearer {{token}}",
  },
  folder: "API/Users",
});

// Create an environment
await mcp.callTool("create_environment", {
  name: "Production",
  workspaceId: "workspace-id",
  values: [
    {
      key: "base_url",
      value: "https://api.production.com",
      type: "default",
    },
    {
      key: "api_key",
      value: "secret-key",
      type: "secret",
    },
  ],
});

🔐 Security

API Key Protection: Store your Postman API key securely using environment variables
Scope Limitation: The API key should have minimal required permissions
Network Security: All requests use HTTPS to communicate with Postman API

🤝 Contributing

Fork the repository
Create your feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add some amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

📞 Support

Create an issue for bug reports or feature requests
Check existing issues before creating new ones
Provide detailed information including error messages and environment details

Made with ❤️ for the developer community