home / mcp / mcp tmux server

MCP TMUX Server

Provides a remote, model-guided control plane for interactive tmux sessions, including session management, pane control, and scrollback visibility across hosts.

Installation

Add the following to your MCP client configuration file.

Configuration

View docs

{
  "mcpServers": {
    "k8ika0s-mcp-tmux": {
      "command": "npx",
      "args": [
        "@k8ika0s/mcp-tmux"
      ],
      "env": {
        "MCP_TMUX_HOST": "your-ssh-alias",
        "MCP_TMUX_SESSION": "collab",
        "MCP_TMUX_TIMEOUT_MS": "15000"
      }
    }
  }
}

You run a remote-aware MCP server that brings a model into a real, inspectable tmux session on a remote host. It anchors the model to concrete state, enabling safe, controlled interactions with live terminals while providing visibility, logging, and structured collaboration with an LLM.

How to use

You drive the remote tmux session from your MCP client by first opening or creating a session on a target host, then sending keystrokes and reading pane output. You can create or reattach to a remote tmux session, read scrollback with full context, move focus between windows and panes, and tail or snapshot outputs. Destructive actions require explicit confirmation, and the system provides defaults to prevent mis-targeting. Use the available tools to open a session, inspect the layout, send commands, capture output, and re-ground the model’s context as needed.

How to install

Prerequisites: install tmux on the local machine and on the remote host(s); install Node.js 18 or newer; ensure SSH access via config aliases.

Install and build the MCP server locally, then start using an optional default host and session.

Step-by-step commands you can run:

Additional sections

Configuration and runtime behavior are designed to keep you in control. You can set default host and session, override the tmux binary path, and adjust timeouts for remote commands. The server records logs locally, keeps audit-friendly history, and exposes a wide range of tools to manage sessions, panes, windows, and layouts. You can enable per-session audit logging to capture commands and outputs in detail, while defaults help prevent accidental destructive actions.

Security and safety notes: destructive actions require confirm=true, and the system logs actions so you can review history. The server runs commands with your user credentials on the remote host, respecting your SSH configuration and permissions. Always verify the exact commands you send and review captured output before making changes to live systems.

Troubleshooting tips: ensure SSH aliases resolve correctly, verify tmux is installed on both local and remote hosts, and check logs under your configured log directory. If a session seems out of sync, re-ground with tmux_state to refresh the model’s view of sessions, windows, panes, and recent scrollback.

Available tools

tmux_open_session

Ensure a remote tmux session exists (create if missing) given a host and session, and set them as defaults.

tmux_default_context

Show detected default session and a quick session listing.

tmux_state

Snapshot sessions, windows, panes, and capture of the active/default pane.

tmux_set_default

Persist defaults for host, session, window, and pane for quick re-grounding.

tmux_get_default

Return the current default host/session/window/pane.

tmux_capture_layout

Save the current window layout for a session.

tmux_restore_layout

Re-apply a saved window layout to a target.

tmux_tail_pane

Poll a pane repeatedly to follow output without reissuing commands.

tmux_tail_task

Task-based tail with polling over time to follow output.

tmux_select_window

Change focus to a specific window within a session.

tmux_select_pane

Change focus to a specific pane.

tmux_set_sync_panes

Toggle synchronize-panes for a window.

tmux_save_layout_profile

Persist a named layout profile for later reuse.

tmux_apply_layout_profile

Apply a named layout profile to a session.

tmux_readonly_state

Capture a read-only snapshot of sessions/windows/panes without changing defaults.

tmux_batch_capture

Capture multiple panes in parallel to gather context quickly.

tmux_run_batch

Run multiple commands in one or more panes with configurable prompt handling and automatic output capture.

tmux_send_keys

Send keystrokes to a target pane, with optional Enter. Supports tokens like <SPACE>, <ENTER>, <TAB>, <ESC>.

tmux_health

Quick health check for tmux reachability and host profile.

tmux_context_history

Pull recent scrollback to extract recent commands and context.

tmux_quickstart

Return a concise playbook for the LLM to start interacting with the remote tmux session.

tmux_multi_run

Fan-out commands and captures to multiple hosts/panes in parallel.

tmux_state_resource

Read the current default snapshot via a resource URI.