cmux-browser-mcp

An MCP (Model Context Protocol) server that gives Claude Code full control of cmux’s embedded browser.

Open pages, click buttons, fill forms, take screenshots, run JavaScript — all from Claude Code, right next to your terminal.

Prerequisites

• cmux (macOS terminal with embedded browser)
• Claude Code CLI (claude)
• Node.js >= 18

Install

git clone https://github.com/jasonraz/cmux-browser-mcp.git
cd cmux-browser-mcp
chmod +x install.sh
./install.sh

Then restart Claude Code. Verify with /mcp — you should see cmux-browser listed.

The install script will:

1. Copy server.mjs and package.json to ~/.claude/mcp-servers/cmux-browser/
2. Run npm install to fetch the MCP SDK dependency
3. Register the server with Claude Code via claude mcp add

Manual Install

If you prefer to do it yourself:

mkdir -p ~/.claude/mcp-servers/cmux-browser
cp package.json server.mjs ~/.claude/mcp-servers/cmux-browser/
cd ~/.claude/mcp-servers/cmux-browser && npm install
claude mcp add cmux-browser --scope user -- node ~/.claude/mcp-servers/cmux-browser/server.mjs

Tools (43)

Tool notes

• browser_click — supports action: click (default), dblclick, focus, scroll-into-view
• browser_press — supports action: press (default), keydown, keyup
• browser_screenshot — accepts optional --json flag via json: true
• browser_tab — action accepts new, list, switch, close, or a numeric tab index

How It Works

The server wraps cmux’s browser CLI subcommands as MCP tools with proper schemas. Claude Code discovers these tools at startup and can call them directly.

The core workflow is snapshot → ref → act:

1. Open a page with browser_open
2. Snapshot the accessibility tree with browser_snapshot — returns element refs like [ref=e1], [ref=e2]
3. Act on elements: browser_click ref e1, browser_fill ref e3 with text
4. Verify with another snapshot or browser_screenshot

Screenshots

browser_screenshot uses cmux browser screenshot --out to capture a PNG directly to disk and returns the file path. Claude Code can then Read the PNG to view it visually.

Configuration

Version compatibility

Tools check cmux’s capabilities endpoint at runtime. If you call a tool that requires a newer version of cmux than you have installed, you’ll get a clear error message telling you which capability is missing — not a cryptic failure.

All tools present in v1.1.x continue to work unchanged.

Gotchas

• CMUX_SURFACE_ID env var: Auto-set in cmux terminal panes. The MCP server strips this from child processes so browser commands target the correct surface instead of the caller’s terminal. This is handled automatically.

• maxBuffer: The server sets maxBuffer to 50 MB for execFile calls to accommodate large command outputs.

Update

git pull
./install.sh

Then restart Claude Code.

Uninstall

claude mcp remove cmux-browser --scope user
rm -rf ~/.claude/mcp-servers/cmux-browser

License

MIT