laszlopere/mcp-tmux

A comprehensive, universal MCP server for
driving **tmux** — sessions, windows, panes, sending keystrokes, and reading
pane output — on the local machine or on remote hosts over SSH.
Source: ** **
Shared, visible sessions — pair with the AI
This is the whole point, not a caveat: the agent drives **real** tmux sessions,
not a private sandbox. When you attach to a session the agent is using, you see
its keystrokes and command output **live**, and you can type into the very same
pane. Nothing the agent does is hidden from an attached human — by design.
That makes tmux a natural medium for **pair programming with the AI**: open a
shared session, watch it work, take the keyboard when you want to step in, and
hand it back. The agent and you cooperate in one place instead of the agent
operating out of sight. (Because writes into an attached session are visible and
real, be deliberate with destructive commands — you're both driving the same
terminal.)
Design goals
- **Comprehensive.** Curated tools cover the common operations ergonomically,
and a raw tmux_command passthrough runs *any* tmux subcommand — so whatever
your tmux supports, this server supports.
- **Universal.** Works against tmux **1.8+** (≈2013 — covers virtually every
live distro). The server detects the target's tmux version and only uses
flags/format variables that version understands.
- **Local + remote.** Any tool can run against the local tmux or a remote host
over SSH (ad-hoc user@host or a named profile from the config file). Old or
minimal boxes only need tmux + ssh; the server itself runs on a modern
host with Python 3.10+.
Install
Requires Python 3.10+ on the host running the server, plus the tmux binary
(and ssh for remote targets).
> **Installing ≠ registering.** Installing the package only puts the mcp-tmux
> executable on your PATH — it does **not** tell any MCP client about it. Python
> wheels can't run post-install code, so registration is always a separate step
> (see below). If a client "can't find" the server after install, it just hasn't
> been registered yet.
Register with Claude Code
The package can register itself — no hand-editing of config files:
**User scope matters.** mcp-tmux register defaults to --scope user, so the
server is visible from **every** directory/session. The plain
claude mcp add tmux -- mcp-tmux defaults to local (project) scope, which is
the usual reason a server "doesn't show up" in another session — it was only
added for the directory you ran it in. To pick a scope explicitly:
After registering, confirm with claude mcp list (you should see
tmux: mcp-tmux - ✓ Connected). A client session already running must be
restarted to pick up a newly registered server.
Equivalent manual form, if you prefer the raw CLI:
One-shot install + register (and clean removal)
From a checkout, the helper scripts do install **and** registration together —
the closest thing to "it happens at install time":
To remove everything by hand:
Run from a checkout (development)
Tools (overview)
Tools are grouped into **toolsets** so a session only pays the schema cost of
what it needs. core is always loaded; the rest are opt-in (see
Selecting toolsets). A default session loads
core + automation (~19 tools); ["all"] loads the full surface (61).
| Toolset | Tools |
|---|---|
| **core** *(always loaded)* | tmux_command, tmux_query, tmux_version, tmux_list_targets, tmux_transport, tmux_has_session, tmux_new_session, tmux_send_keys, tmux_capture_pane, tmux_new_window, tmux_list_panes, tmux_split_window, tmux_list, tmux_kill, tmux_rename, tmux_select |
| automation *(default)* | tmux_wait_for_text, tmux_wait_for_idle, tmux_run |
| layout | tmux_next_layout, tmux_move_window, tmux_select_layout, tmux_resize_pane, tmux_set_pane_title, tmux_clear_history, tmux_swap, tmux_last, tmux_respawn, tmux_link_window, tmux_unlink_window, tmux_break_pane, tmux_join_pane, tmux_find_window, tmux_pipe_pane |