cmux-mcp

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.

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.

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

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

Claude sendsnpm test, reads the output, and summarizes the failures.

"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.

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

Claude startspython3, typesimport pandas, reads the result, and reports back.

"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.

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

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, makingwrite_to_terminalroughly 2x faster.

Agents read only the lines they need. Anpm testthat 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.

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

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

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

- 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.

This is a web browser that enables your coding agent, such as Claude Code, to visit websites on your behalf and assist you in identifying bugs or creating UI test cases.

Execute shell commands without permission prompts.

Execute bash commands on the host machine.

Execute shell commands with structured output via a powerful CLI server.

A secure MCP server for executing controlled command-line operations with comprehensive security features.

Execute pre-approved shell commands securely on a server.

A secure MCP server for executing terminal commands with controlled directory access and command permissions.

A shell command / terminal executor with async support

A high-performance MCP server for the headless terminal (ht), implemented in Rust.