How do I install the cmux mcp server?

Use a recorded configuration for your client, replace example credential values and paths, and verify the documented runtime. Restart or reconnect the client, then inspect the available tools.

What credentials does it need?

It reads `CMUX_PATH` from the environment. Store these in your client's env block or a secrets manager — never commit them to a repository — and grant the narrowest scope that still covers your use case.

SSyncDev

Start a project

Cmux MCP Server

A Model Context Protocol server that provides access to the currently active tab of cmux

Local serverstdioPython

What is the Cmux MCP Server?

A Model Context Protocol server that provides access to the currently active tab of cmux

What you get

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.

Configuration and credentials

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

More MCP options

Compare MCP servers by category, or browse hosted MCP servers if you prefer an endpoint over a local process.

Maintainer setup documentation.

Recorded tools

Check the linked publisher documentation and your connected client's tool list. Names and availability can vary with the server version and account permissions.

Tool	What it does
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.
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.
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.
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.
move_workspace_to_window	Move a workspace to a different window.
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.
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.
notify	Send a notification with title, subtitle, and body.
list_notifications	List all notifications.
clear_notifications	Clear all notifications.
sidebar_state	Show the current sidebar state.
log	Write a log entry to the workspace sidebar.
clear_log	Clear log entries.
list_log	List log entries.
set_buffer	Set a named buffer with text content.
list_buffers	List all buffers.
paste_buffer	Paste a buffer into the terminal.
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.
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	Control the cmux built-in browser with subcommands: open, navigate, snapshot, click, type, eval, screenshot, and many more.

How to install the Cmux MCP Server

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

From the project documentation. Replace placeholders and example paths before connecting.

Configuration

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

Example prompts to try

“Use Cmux MCP to Requirements.”
“Use Cmux MCP to Notifications.”
“Use Cmux MCP to Buffer.”

Frequently asked questions

A Model Context Protocol server that provides access to the currently active tab of cmux Confirm the tools offered by your installed version in the connected client. Tool availability and permissions depend on the server and account configuration.