cmux-mcp

한국어

MCP server that gives AI agents full control of your cmux terminal.

Let Claude run commands, read output, manage tabs/panes/workspaces/windows, and send control characters in your cmux terminal -- all through the Model Context Protocol. Works in the background. No focus stealing.

Quick Start

Option A: Claude Code Plugin (Recommended)

/plugin marketplace add daegweon/cmux-mcp
/plugin install cmux-mcp@cmux-tools

That's it. The MCP server is configured automatically.

Option B: npx (No build required)

Edit ~/.claude/settings.json:

{
  "mcpServers": {
    "cmux-mcp": {
      "command": "npx",
      "args": ["-y", "cmux-mcp"]
    }
  }
}

Restart Claude Code.

Option C: Clone and build

git clone https://github.com/daegweon/cmux-mcp.git
cd cmux-mcp
npm install && npm run build

Edit ~/.claude/settings.json:

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

Restart Claude Code.

Claude Desktop setup

Edit ~/Library/Application Support/Claude/claude_desktop_config.json:

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

Restart Claude Desktop after saving.

Any MCP client

cmux-mcp communicates over stdio. Point your MCP client to node /path/to/cmux-mcp/build/index.js.

Requirements

• macOS
• cmux.app installed and running
• Node.js 18+
• cmux socket control mode set to Automation or Open Access (Settings > Automation > Socket Control Mode)

Tools

cmux-mcp exposes the full cmux CLI as MCP tools. All terminal I/O tools support an optional surface parameter for targeting specific tabs.

Terminal I/O

Tool	Description
write_to_terminal	Send commands to the terminal. Enter is appended automatically. Returns new output line count.
read_terminal_output	Read the last N lines from the terminal buffer.
send_control_character	Send Ctrl+C, Ctrl+Z, Escape, or any control character.

Surface (Tab) Management

Tool	Description
list_surfaces	List all tabs in a workspace with IDs and titles.
new_surface	Create a new terminal tab.
close_surface	Close a specific tab.
focus_surface	Focus (activate) a specific tab.
move_surface	Move a tab to a different pane, window, or position.
reorder_surface	Reorder a tab within its pane.
rename_tab	Rename a tab.
new_split	Split the current surface into a new pane.
drag_surface_to_split	Drag a surface to create a split.
refresh_surfaces	Refresh all surfaces.
surface_health	Check health of surfaces.

Pane Management

Tool	Description
list_panes	List all panes in a workspace.
new_pane	Create a new pane (split) with direction.
focus_pane	Focus a specific pane.
resize_pane	Resize a pane in a given direction.
swap_pane	Swap two panes.
break_pane	Break a pane out into a new workspace.
join_pane	Join a pane into another pane.
last_pane	Switch to the last active pane.
list_panels	List all panels in a workspace.
focus_panel	Focus a specific panel.

Window Management

Tool	Description
list_windows	List all windows.
new_window	Create a new window.
close_window	Close a specific window.
focus_window	Focus a specific window.
current_window	Show current window info.
rename_window	Rename the current window.
next_window / previous_window / last_window	Navigate between windows.
move_workspace_to_window	Move a workspace to a different window.

Workspace Management

Tool	Description
list_workspaces	List all workspaces.
new_workspace	Create a new workspace with optional cwd/command.
close_workspace	Close a specific workspace.
select_workspace	Switch to a specific workspace.
rename_workspace	Rename a workspace.
current_workspace	Show current workspace info.
reorder_workspace	Reorder a workspace in the sidebar.

Search & Structure

Tool	Description
find_window	Search for a window by content or title.
tree	Show the full tree structure (windows/workspaces/panes/surfaces).
identify	Show identity info for the current surface/workspace.

Notifications

Tool	Description
notify	Send a notification with title, subtitle, and body.
list_notifications	List all notifications.
clear_notifications	Clear all notifications.

Sidebar Metadata

Tool	Description
set_status / clear_status / list_status	Manage status entries in the sidebar.
set_progress / clear_progress	Manage a progress bar in the sidebar.
sidebar_state	Show the current sidebar state.

Log

Tool	Description
log	Write a log entry to the workspace sidebar.
clear_log	Clear log entries.
list_log	List log entries.

Buffer

Tool	Description
set_buffer	Set a named buffer with text content.
list_buffers	List all buffers.
paste_buffer	Paste a buffer into the terminal.

Terminal Control

Tool	Description
clear_history	Clear terminal scrollback history.
capture_pane	Capture pane content (tmux-compatible).
respawn_pane	Respawn a pane (restart the shell).
pipe_pane	Pipe pane output to a shell command.
display_message	Display a message overlay.
trigger_flash	Trigger a visual flash on the terminal.

Hooks & Misc

Tool	Description
set_hook	Set, list, or unset event hooks.
wait_for	Wait for or send a named signal.
set_app_focus	Set the app focus state.
markdown_open	Open a markdown file in a formatted viewer with live reload.
version	Show cmux version.
ping	Ping the cmux socket.

Browser

Tool	Description
browser	Control the cmux built-in browser with subcommands: open, navigate, snapshot, click, type, eval, screenshot, and many more.

Real-World Examples

Run tests and analyze failures:

"Run the test suite and tell me which tests are failing"

Claude sends npm test, reads the output, and summarizes the failures.

Multi-tab SSH sessions:

"Open two new tabs, SSH into server-a in one and server-b in the other, then compare their disk usage"

Claude creates tabs, sends SSH commands to each, reads output from both, and compares.

Interactive REPL session:

"Open a Python REPL and check if pandas is installed"

Claude starts python3, types import pandas, reads the result, and reports back.

Long-running process management:

"Start the dev server, wait for it to be ready, then run the health check"

Claude sends the start command, polls the output until "ready" appears, then runs the next command.

Why cmux-mcp?

Background operation

cmux-mcp uses cmux's native CLI (cmux send, cmux read-screen, cmux send-key) which communicates via Unix socket. This means:

• Works while cmux is in the background
• No window focus stealing
• No AppleScript activation delays
• Reliable even during app initialization

CLI vs AppleScript

This project was forked from ferrislucas/iterm-mcp and completely rewritten. Here's why:

	AppleScript (iterm-mcp)	cmux CLI (cmux-mcp)
Focus	May steal focus, activate app	No focus change, Unix socket
Buffer reading	Ghostty write_scrollback_file (debug-only)	cmux read-screen (stable production API)
Startup	Fails if app not fully initialized	Socket-based, more resilient
Targeting	Always "front window"	--surface flag for precise pane targeting
Key support	ASCII codes only	Named keys: ctrl+c, escape, enter, arrows
Stability	Fragile to app state changes	Decoupled via socket IPC

Smart completion detection

cmux-mcp doesn't just blindly wait after sending a command. It monitors the TTY's CPU activity to know when a command actually finishes -- even for commands that produce output over time. As of v1.3.1, the polling interval was reduced from 350ms to 150ms and the idle threshold from 1000ms to 500ms, making write_to_terminal roughly 2x faster.

Token efficient

Agents read only the lines they need. A npm test that produces 500 lines of output? The agent first gets told "500 lines were output", then reads just the last 20 lines to check for errors. No wasted context window.

Handling Known cmux Issues

cmux-mcp's architecture avoids several known cmux edge cases:

Issue	Problem	How cmux-mcp handles it
#152	read-screen was debug-only	Uses the now-stable production CLI
#2042	Invalid surface ID silently falls back to focused pane	Architecture supports --surface for explicit targeting
#1715	TabManager unavailable during startup breaks hooks	Socket-based CLI avoids initialization timing issues
#2153	send-key didn't support arrow keys	Uses the updated upstream API with full key support
#2210	Sidebar toggle corrupts prompt via SIGWINCH	Reads buffer after settling delay to avoid corrupted output

Architecture

MCP Client (Claude Code, Claude Desktop, etc.)
    |  stdio
cmux-mcp server
    |  child_process
cmux CLI (send / read-screen / send-key / ...)
    |  Unix socket
cmux.app (Ghostty-based terminal)
    |
macOS PTY

Core modules:

Module	Role
cmux-path	Resolves cmux binary path: CMUX_PATH env > which cmux > macOS default paths > fallback
CommandExecutor	Sends commands via cmux send, waits for completion. Caches TTY path for 60s.
TtyOutputReader	Reads terminal buffer via cmux read-screen
SendControlCharacter	Sends control keys via cmux send-key
ProcessTracker	Monitors TTY processes for completion detection

Development

npm run build          # Compile TypeScript
npm run watch          # Auto-rebuild on changes
npm test               # Run unit tests
npm run e2e            # Run E2E tests (requires running cmux)
npm run inspector      # Open MCP Inspector for interactive debugging

Safety

• No built-in command restrictions. Commands run with your shell's permissions.
• Monitor AI activity and interrupt if needed.
• Start with focused tasks until you're familiar with the model's behavior.

Credits

• Forked from ferrislucas/iterm-mcp
• Built for cmux by manaflow.ai

Privacy

cmux-mcp does not collect or transmit any data. All processing is local. See PRIVACY.md for details.

License

MIT