cmux-mcp

MCP server wrapping the cmux CLI. Lets an MCP client (Claude Code, etc.) drive cmux panes, workspaces, terminal input, and the embedded browser.

It shells out to the cmux binary — cmux handles socket auth and ref parsing, so this stays a thin, robust layer rather than re-speaking the Unix-socket RPC.

Tools

The browser and raw passthroughs cover cmux's full surface without exploding the tool list into ~90 entries. The typed tools just save the agent from hand-assembling argv for the common verbs.

Workspace targeting

cmux defaults pane/workspace-spawning commands to the focused workspace, which drifts as the user clicks around. When a tool call omits workspace, the server falls back to CMUX_WORKSPACE_ID from its own environment — i.e. the workspace the MCP client (and this server) was launched in — so new panes land where the user is actually working. Pass workspace explicitly to override.

"Close this workspace" safety

cmux identify returns two refs: caller (the pane the calling process actually runs in) and focused (the workspace with UI focus right now). These differ — an agent runs in workspace A while the user clicks into workspace B, so B is focused.

cmux_close_current_workspace always resolves the target from identify.caller.workspace_ref, never focused. If caller is null (invoked outside a cmux terminal) it refuses and asks for an explicit ref rather than guessing from focus. The first call only previews the resolved target (About to close workspace:5 — user-roles-3. Confirm?); you must call again with confirm=true to actually close — so a wrong target is caught before it's destructive.

Do not use identify --no-caller (or read focused.workspace_ref) when the intent is "act on my own workspace" — it drops caller and can close whatever the user last clicked. --no-caller is only for queries about UI focus.

Install

Requires Node ≥ 18 and the cmux app (the cmux binary).

Without cloning (recommended)

npx installs and builds straight from GitHub — no clone, no manual build:

claude mcp add cmux -- npx -y github:puchkoff/cmux-mcp

The first run compiles the TypeScript (via the package's prepare step) and caches it; later runs start instantly.

From a clone

git clone https://github.com/puchkoff/cmux-mcp.git
cd cmux-mcp
npm install
npm run build        # compiles to dist/

Register with Claude Code

If you cloned, register with the absolute path to the built entrypoint:

claude mcp add cmux -- node /absolute/path/to/cmux-mcp/dist/index.js

• --scope user registers it for every project (default is the current project).

• After adding, restart Claude Code (or reconnect via /mcp) — MCP tools load at session start.

• Verify: claude mcp get cmux should report ✓ Connected. The cmux_* tools then appear.

Or register by hand in .mcp.json / settings:

{
  "mcpServers": {
    "cmux": {
      "command": "node",
      "args": ["/absolute/path/to/cmux-mcp/dist/index.js"]
    }
  }
}

Works with any MCP client (Cursor, etc.) — point it at node dist/index.js.

Env

• CMUX_BIN — path to the cmux binary if it isn't on PATH (bundled at /Applications/cmux.app/Contents/Resources/bin/cmux on macOS).

• CMUX_WORKSPACE_ID — default workspace ref (auto-set inside a cmux pane).