@postman/postman-mcp-cli

Postman MCP Runner

A CLI tool to download, extract, and run MCP (Model Context Protocol) servers from S3. This tool simplifies the process of running MCP servers by handling the download, extraction, and execution in a single command.

Features

• 🔄 Downloads MCP server ZIP files from S3 by ID
• 📦 Extracts server files and dependencies
• 🚀 Runs MCP servers with proper stdin/stdout communication
• 📚 Handles node_modules dependencies (downloads pre-built ZIP or falls back to npm install)
• 🔧 Supports bidirectional communication for MCP protocol

Installation

Prerequisites

• Node.js (v18.19.1 or later recommended)
• npm or yarn

Install from source

# Clone the repository
git clone <repository-url>
cd mcp-runner-lib

# Install dependencies
npm install

# Link the CLI tool globally (optional)
npm link

Usage

Basic Usage

# Run an MCP server by ID
node bin/cli.js <server-id>

# Example
node bin/cli.js my-mcp-server-123

If installed globally

# If you ran npm link, you can use the command directly
postman-mcp-runner <server-id>

How it Works

• Download: Fetches the MCP server ZIP file from S3 using the provided ID
• Extract: Unzips the server files to a temporary directory
• Dependencies: Downloads pre-built node_modules ZIP or runs npm install
• Execute: Runs node mcpServer.js with proper stdin/stdout piping for MCP protocol communication

Architecture

The tool consists of two main components:

• CLI Interface (bin/cli.js): Handles command-line arguments and invokes the runner
• Runner (lib/runner.js): Core logic for downloading, extracting, and running MCP servers

MCP Protocol Support

The runner is designed to work with the Model Context Protocol, providing:

• Bidirectional communication via stdin/stdout
• Proper process piping for MCP client-server communication
• Support for Postman MCP client integration

Development

Project Structure

mcp-runner-lib/
├── bin/
│   └── cli.js          # CLI entry point
├── lib/
│   └── runner.js       # Core runner logic
├── package.json        # Project configuration
└── README.md          # This file

Dependencies

• adm-zip: ZIP file extraction
• axios: HTTP requests for downloading files

Building

# Install dependencies
npm install

# Run the CLI tool
node bin/cli.js <server-id>

Error Handling

The tool includes comprehensive error handling for:

• Missing server ID parameter
• Network download failures
• ZIP extraction errors
• Missing server files
• npm install failures

Troubleshooting

Common Issues

• "Usage: mcp-run " error

  • Make sure you're providing a server ID as an argument

• Download failures

  • Check your internet connection
  • Verify the server ID exists in the S3 bucket

• Extraction errors

  • Ensure you have write permissions in the temp directory
  • Check if the ZIP file is corrupted

• Node.js version issues

  • The tool is configured to use Node.js v18.19.1
  • Update the path in runner.js if using a different version