mpak run

Run an MCP server directly from the registry. Bundles are cached locally for fast subsequent runs.

Usage

mpak run <package>

Tip

mpak run is a shortcut for mpak bundle run. Both work identically.

Examples

# Run latest version
mpak run @nimblebraininc/echo

# Run specific version
mpak run @nimblebraininc/[email protected]

# Force re-download (update cache)
mpak run @nimblebraininc/echo --update

# Run a local .mcpb bundle file
mpak run --local ./path/to/bundle.mcpb

Options

Option	Description
--update	Force re-download even if cached
-l, --local <path>	Run a local .mcpb bundle file instead of fetching from the registry

How It Works

1. Check cache - Look for bundle in ~/.mpak/cache/
2. Download - If not cached (or --update), download from registry
3. Extract - Unzip the .mcpb file
4. Run - Execute the server using the bundled configuration

The server runs in the foreground, communicating via stdio (JSON-RPC).

Integration with Claude

See the Integrations section for setting up mpak bundles with:

• Claude Code - One command: claude mcp add --transport stdio echo -- mpak run @nimblebraininc/echo
• Claude Desktop - JSON config file

Environment Variables

When mpak run spawns a bundle, it sets the following environment variables:

Variable	Default	Description
MPAK_WORKSPACE	$CWD/.mpak	Project-local directory for stateful data. Bundles should read/write persistent data here instead of using relative paths.

Override the workspace directory:

MPAK_WORKSPACE=/data/my-project mpak run @nimblebraininc/leadgen

Bundles access it via standard environment variable APIs:

import os
workspace = os.environ.get("MPAK_WORKSPACE", ".")

const workspace = process.env.MPAK_WORKSPACE ?? ".";

Configuration

Some bundles require configuration (API keys, etc.). See mpak config for storing configuration values.

Troubleshooting

Bundle not found

Error: No bundle found for @owner/package on darwin-arm64

The bundle may not be available for your platform. Check available platforms with mpak bundle show.

Python not found

Error: python3 not found

Python-based bundles require Python 3.10+ to be installed and available in your PATH.