Tmux MCP Server

An MCP (Model Context Protocol) server that provides programmatic control over tmux terminal sessions. Enables Claude (or other MCP clients) to create, manage, and interact with tmux sessions for SSH access, command execution, and terminal automation.

Features

Create and manage tmux sessions
Send commands to sessions
Capture pane output
Split windows and manage panes
Full control over terminal sessions via MCP tools

Installation

Prerequisites

Node.js (v16 or higher)
tmux installed on your system
For Windows: WSL2 with tmux installed

Setup

Clone or download this repository
Install dependencies:

npm install

Make the server executable:

chmod +x src/index.js

Configuration

Add the server to your Claude Desktop configuration file:

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

Windows: %APPDATA%\Claude\claude_desktop_config.json

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

For WSL2 on Windows, you can use wsl to run the server:

{
  "mcpServers": {
    "tmux": {
      "command": "wsl",
      "args": ["node", "/home/username/tmux-mcp-server/src/index.js"]
    }
  }
}

Restart Claude Desktop after updating the configuration.

Available Tools

tmux_create_session

Create a new tmux session.

session_name (optional): Name for the session
start_directory (optional): Starting directory

tmux_list_sessions

List all active tmux sessions with details.

tmux_send_keys

Send keys/commands to a session.

session_name (required): Target session name
keys (required): Keys or command to send
literal (optional): If true, don't append Enter

tmux_capture_pane

Capture the visible content of a pane.

session_name (required): Target session name
pane_index (optional): Pane index (default: "0")
lines (optional): Number of lines from scrollback (-1 for all)

tmux_kill_session

Terminate a tmux session.

session_name (required): Session to kill

tmux_split_window

Split a window to create a new pane.

session_name (required): Target session name
vertical (optional): If true, split vertically (side by side)

tmux_select_pane

Select a specific pane in a session.

session_name (required): Target session name
pane_index (required): Pane index to select

tmux_list_panes

List all panes in a session with details.

session_name (required): Target session name

Usage Examples

SSH to a CML Console Server

Claude: Create a tmux session named "cml-console"
Claude: Send SSH command to connect to CML console server
Claude: Capture pane to see login prompt
Claude: Send credentials
Claude: Send "open router1" to access device console
Claude: Capture pane to see device output
Claude: Send configuration commands

Monitor Multiple Devices

Claude: Create session "monitoring"
Claude: Split window vertically
Claude: Select pane 0, SSH to device1
Claude: Select pane 1, SSH to device2
Claude: Capture both panes to see simultaneous output

Use Cases

CML Device Access: SSH to CML console servers and access node consoles
Configuration Management: Send commands to network devices and capture output
Troubleshooting: Interactive debugging of network issues
Automation: Script complex terminal workflows
Testing: Automated testing of CLI applications
Monitoring: Watch multiple terminal sessions simultaneously

Troubleshooting

Sessions not appearing

Ensure tmux is installed and accessible in your PATH:

which tmux
tmux -V

WSL2 connectivity issues

Make sure you can run tmux from WSL2:

wsl tmux new-session -d -s test
wsl tmux list-sessions
wsl tmux kill-session -t test

Command not executing

Check if the session exists:

tmux list-sessions

License

MIT