mcpbundles 1.5.4

MCPBundles CLI — connect AI to all your MCP tools from the command line

MCPBundles CLI

Connect AI to 500+ tools from the command line.

The mcpbundles CLI provides full MCP (Model Context Protocol) access to the MCPBundles platform — tool discovery, execution, interactive shell, AI agent integration, and a desktop proxy tunnel for local services.

Features

• Hub MCP access — discover and call 500+ tools directly from your terminal
• Interactive shell — REPL with tab completion, command history, and live connection switching
• Multi-connection support — connect to Hub, individual bundles, or different workspaces simultaneously
• Aggregated local proxy — expose multiple connections as a single unauthenticated MCP endpoint
• AI agent integration — generate tool manifests for AI coding agents
• Code execution — run sandboxed code with --stream for progressive output
• Desktop proxy tunnel — securely forward cloud requests to local services (databases, browsers, APIs)
• Rich terminal output — tables, syntax highlighting, JSON, streaming, and NO_COLOR support
• Multiple auth methods — OAuth2 PKCE (browser) or API key (CI/CD)
• Shell completion — dynamic tab completion for bash, zsh, and fish

Installation

pip install mcpbundles

Quick Start

# Authenticate (opens browser)
mcpbundles login

# Or use an API key (CI/CD, headless)
mcpbundles login --api-key mb_your_key_here

# List available tools
mcpbundles tools

# Get full schema for a tool
mcpbundles tools code_execution

# Call a tool
mcpbundles call get-contacts limit=10

# Execute code
mcpbundles exec "result = 2 + 2; print(result)"

# Execute from file with streaming output
mcpbundles exec -f script.py --stream

# Start interactive shell
mcpbundles shell

Commands

Auth & Identity

Command	Description
mcpbundles login	Authenticate via browser (OAuth2 PKCE)
mcpbundles login --api-key mb_...	API key auth (headless/CI)
mcpbundles logout	Remove stored credentials
mcpbundles whoami	Show current user, workspace, and server

Tool Discovery (always live from server)

Command	Description
mcpbundles tools	List all available MCP tools
mcpbundles tools <name>	Show full schema for a specific tool
mcpbundles tools -f <keyword>	Filter tools by name or description
mcpbundles tools --json	JSON output for piping
mcpbundles resources	List available MCP resources
mcpbundles prompts	List available MCP prompts

Tool Execution

Command	Description
mcpbundles call <tool> key=value	Call a tool with typed arguments
mcpbundles call <tool> key:=true	JSON-typed argument (bool, number, array)
mcpbundles call <tool> -f data.json	Arguments from JSON file
mcpbundles read <uri>	Read an MCP resource
mcpbundles prompt <name> key=value	Get an MCP prompt
mcpbundles exec "code"	Execute code (shortcut for code_execution)
mcpbundles exec -f script.py	Execute code from file
mcpbundles exec -f script.py --stream	Stream output line-by-line

Named Connections

Command	Description
mcpbundles connect --as hub	Connect to Hub (default)
mcpbundles connect --as hubspot --bundle hubspot	Direct bundle connection
mcpbundles connect --as dev --server localhost:8000	Dev server connection
mcpbundles connections	List active connections
mcpbundles disconnect <name>	Remove a connection
mcpbundles tools --as @hubspot	Target a specific connection

Interactive Shell

$ mcpbundles shell
MCPBundles Shell — connecting to hub...
Connected. Type help for commands, exit to quit.

mcpbundles(hub)> tools
mcpbundles(hub)> call get-contacts limit=5
mcpbundles(hub)> exec print("hello world")
mcpbundles(hub)> use hubspot          # switch connection live
mcpbundles(hubspot)> tools
mcpbundles(hubspot)> exit

AI Agent Integration

Command	Description
mcpbundles init	Generate tool manifest (mcpbundles_tools.md)
mcpbundles init --format json	JSON format manifest
mcpbundles serve	Local MCP proxy on localhost:8080
mcpbundles serve --connections hub,hubspot,stripe	Aggregate multiple connections

Local MCP Proxy (serve)

Start a local unauthenticated MCP server that proxies to remote MCPBundles:

# Single connection
mcpbundles serve --port 8080

# Multi-connection aggregation
mcpbundles serve --connections hub,hubspot,stripe

In aggregated mode, list_tools merges tools from all connections and call_tool routes to the correct upstream automatically. Local AI clients connect without credentials.

Desktop Proxy Tunnel

Command	Description
mcpbundles proxy start	Start WebSocket tunnel daemon
mcpbundles proxy stop	Stop tunnel daemon
mcpbundles proxy restart	Restart tunnel
mcpbundles proxy status	Show tunnel status
mcpbundles proxy logs	View tunnel logs
mcpbundles proxy logs -f	Follow logs in real-time

Configuration

Command	Description
mcpbundles config show	Show all settings
mcpbundles config set key value	Set a config value
mcpbundles config get key	Get a config value
mcpbundles config reset	Reset to defaults

Shell Completion

mcpbundles install-completion bash    # or zsh, fish

After installation, restart your shell for tab completion on commands, tool names, resource URIs, and connection names.

Output Modes

Flag	Behavior
--pretty	Rich tables, colors, syntax highlighting (default for discovery)
--json	Raw JSON to stdout, pipe-friendly (default for execution)
--raw	Full MCP response envelope (debugging)
--stream	Progressive line-by-line output (for exec)
-q / --quiet	Suppress non-essential output

Respects NO_COLOR environment variable.

Exit Codes

Code	Meaning
0	Success
1	User/input error (bad args, missing auth)
2	Tool execution error (tool returned isError)
3	Connection/server error (unreachable, 5xx)
4	Internal error

Configuration Files

All configuration is stored in ~/.mcpbundles/ (or ~/.mcpbundles-dev/ with ENVIRONMENT=development):

File	Purpose
config.yaml	CLI settings (server, workspace, output format)
token.json	Encrypted OAuth tokens
sessions/	Named connection session files
completion_cache.json	Tab completion cache (60s TTL)
shell_history	REPL command history
tunnel.pid	Proxy daemon PID
tunnel.log	Proxy daemon logs

Config precedence (highest wins):

1. CLI flags (--url, --json, -q)
2. Environment variables (MCPBUNDLES_API_KEY, MCPBUNDLES_BASE_URL)
3. Config file (~/.mcpbundles/config.yaml)
4. Defaults

Security

• OAuth2 PKCE — no client secret stored on disk
• API keys prefixed mb_ — recognized and routed automatically
• Tokens encrypted with machine-specific Fernet key
• File permissions set to user-only (0600)
• Desktop proxy only forwards to localhost
• All tunnel traffic encrypted over WSS

Requirements

• Python 3.10+
• macOS or Linux
• Google Chrome (optional, for browser proxy feature)

Development

git clone https://github.com/thinkchainai/mcpbundles-proxy.git proxy
cd proxy
python -m venv .venv && .venv/bin/pip install -e ".[dev]"
pytest

Support

• Docs: https://mcpbundles.com/docs
• Email: [e-mail]

License

MIT License