Cmux

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

Tool	What it does
cmux_identify	Current + focused window/workspace/pane/surface refs (JSON)
cmux_tree	window > workspace > pane > surface hierarchy
cmux_list	List windows / workspaces / panes / groups
cmux_capture	Read a terminal surface's screen / scrollback (workspace/window-aware)
cmux_new_pane	Split a new terminal or browser pane (optional anchor_pane for deterministic placement)
cmux_new_workspace	Create a workspace (name, cwd, startup command, optional group)
cmux_config	Inspect/reload cmux.json — doctor, path/docs, reload, get/set font-size keys
cmux_surface_health	List health details (e.g. stuck/unresponsive terminals) for surfaces in a workspace
cmux_new_group	Group workspaces under a collapsible sidebar header
cmux_group_action	rename / collapse / expand / pin / focus / set-color / set-icon / move / ungroup / delete (confirm-guarded) a group
cmux_group_members	add / remove / set-anchor of a group's member workspaces
cmux_rename_workspace	Retitle a workspace (via workspace-action)
cmux_rename_tab	Retitle a tab (the pane's tab label, via rename-tab)
cmux_focus_pane	Focus a pane
cmux_close	Close a surface or workspace (explicit ref, or "current" to safely close the calling pane's own workspace, confirm-guarded)
cmux_send	Type literal text into a pane (no Enter, workspace/window-aware)
cmux_send_key	Send a named key (Enter, C-c/ctrl+c, …)
cmux_list_panels	List a workspace's panels to discover a panel ref
cmux_send_panel	Send text to an agent panel (send-panel)
cmux_wait_ready	Poll a panel until it's ready for input (vs. sleeping)
cmux_notify	Post a cmux notification
cmux_browser	Passthrough for any cmux browser subcommand (args array)
cmux_raw	Escape hatch — run any cmux subcommand

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.

Driving a surface in another workspace

cmux_send, cmux_send_key, and cmux_capture resolve a bare surface:N ref against the caller's workspace. To drive a pane in a workspace you spawned elsewhere (e.g. a cmux_new_workspace running Claude), pass workspace (and window if needed) alongside surface. Without it cmux can't find the ref and reports a misleading Surface is not a terminal; these tools now rewrite that to name the surface's real workspace and tell you which workspace= to pass.

For agent panels (cmux claude-teams), discover the ref with cmux_list_panels, drive it with cmux_send_panel, and use cmux_wait_ready (with a pattern matching the input prompt) to know when it accepts input instead of sleeping.

Splitting next to a specific pane (anchor_pane)

cmux new-pane has no pane-anchor flag — it splits the target workspace's active pane — so a bare "split right" lands wherever focus drifted, possibly in a different workspace than the caller. cmux_new_pane accepts an optional anchor_pane (a pane:N or surface:N ref): the server looks up the workspace that pane lives in, focuses it there, then splits — so the new pane lands next to that exact pane regardless of current UI focus. Pass your own cmux_identify → caller.pane_ref to place panes next to yourself.

Target resolution order: anchor_pane > workspace > the caller's workspace (CMUX_WORKSPACE_ID / identify.caller) > the focused workspace. The caller's workspace beats focused because an MCP caller almost always wants the new pane next to itself, not wherever a human last clicked.

"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 with ref: "current" 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).