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.

{
  "mcpServers": {
    "cmux-mcp": {
      "command": "node",
      "args": ["/absolute/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

Surface (Tab) Management

Pane Management

Window Management

Workspace Management

Search & Structure

Notifications

Sidebar Metadata

Log

Buffer

Terminal Control

Hooks & Misc

Browser

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:

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:

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:

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