postman-mcp

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

1. Go to Postman Account Settings
2. Click "Generate API Key"
3. 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

1. Clone the repository:

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

2. Install dependencies:

   npm install
   

3. Set up environment:

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

4. Build the project:

   npm run build
   

5. 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

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

📄 License

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

🔗 Links

• Postman API Documentation
• Model Context Protocol Specification
• MCP SDK Documentation

📞 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