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: https://github.com/laszlopere/mcp-tmux

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

uvx mcp-tmux            # run directly with uv (no install)
# or install it as an isolated, easily-removable tool:
uv tool install mcp-tmux
# or
pipx install mcp-tmux

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:

mcp-tmux register        # add to Claude Code at *user* scope
mcp-tmux unregister      # remove it again

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:

mcp-tmux register --scope user      # everywhere (default)
mcp-tmux register --scope project   # shared via this repo's .mcp.json
mcp-tmux register --scope local     # just this directory

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:

claude mcp add -s user tmux -- mcp-tmux     # for an installed tool
claude mcp add -s user tmux -- uvx mcp-tmux # without installing

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

scripts/install.sh        # build wheel, `uv tool install`, then `mcp-tmux register`
scripts/uninstall.sh      # `mcp-tmux unregister`, then `uv tool uninstall`

To remove everything by hand:

mcp-tmux unregister       # drop it from Claude Code
uv tool uninstall mcp-tmux   # remove the isolated tool (or: pipx uninstall mcp-tmux)

Run from a checkout (development)

python -m mcp_tmux       # stdio server

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 (~18 tools); ["all"] loads the full surface (60).

Every tool accepts an optional target (omit / "local", a named profile, or
user@host). For anything not covered by a dedicated tool — including anything
gated out of the active toolsets — use tmux_command(args=[...]), which is in
core and reaches every tmux subcommand.

Selecting toolsets

Pick toolsets with the toolsets config key or the MCP_TMUX_TOOLSETS
environment variable (comma-separated; env wins over config). core is always
included. The special value all loads every toolset. An unknown name is a
startup error listing the valid toolsets.

# ~/.config/mcp-tmux/config.toml
toolsets = ["core", "automation", "stream"]   # or ["all"] for the full surface

// or in the MCP server env, e.g. Claude Code's mcp config:
"env": { "MCP_TMUX_TOOLSETS": "core,layout,stream" }

With no setting, the default is ["core", "automation"].

The consolidated tools take a kind discriminator instead of having one
tool per entity — e.g. tmux_kill(kind="window", id="dev:2"),
tmux_kill(kind="server"), tmux_swap(kind="pane", src="%1", dst="%2"),
tmux_rename(kind="session", id="old", new_name="new"),
tmux_list(kind="window", scope="dev"). Valid kinds: kill →
session/window/pane/server; rename → session/window; select/last/swap →
window/pane; respawn → pane/window; list → session/window/client/buffer
(tmux_list returns {items, kind}; panes have their own tmux_list_panes
because they scope by window or session).

Live streaming (opt-in)

The one-shot CLI is the universal default. For watching a pane as it
produces output — a build, a tail, a long job — tmux_stream_* opens a
persistent control-mode (tmux -C) connection and lets you long-poll its
event stream instead of repeatedly calling tmux_capture_pane:

tmux_stream_start(session="work")          # -> {"stream_id": "cm-1a2b3c4d", ...}
tmux_stream_read("cm-1a2b3c4d", timeout=10, kinds=["output"])
#   -> blocks until output, then {"events": [{"type":"output","pane":"%0",
#                                             "data":"...","seq":42}], "cursor":42}
tmux_stream_stop("cm-1a2b3c4d")            # detaches; the session keeps running

tmux_stream_read auto-advances a cursor, so just call it again for the next
batch; filter by pane and/or kinds ("output", "window-add",
"layout-change", …). One connection is shared per (target, session) and
tmux_stream_start is idempotent.

Read-only state is also exposed as MCP resources: tmux://sessions,
tmux://{session}/windows, tmux://{window}/panes (local), plus target-aware
variants tmux://{target}/sessions, tmux://{target}/{session}/windows,
tmux://{target}/{window}/panes.

A typical agent flow:

tmux_new_session(detached=True)            # -> {"id": "$0", "name": "0"}
tmux_send_keys("0", text="echo hi", enter=True)
tmux_capture_pane("0")                     # -> {"content": "... hi ..."}

Where send_keys text is evaluated

tmux_send_keys types its text into the pane — it is not a local shell
command. So any shell syntax in it ($(...), backticks, $VAR, ~, globs, …)
is expanded by the shell running in that pane, at the moment the keys are
executed — not on the machine running this MCP server. For an SSH target that
means the remote pane's shell does the expansion; the server only ships the
literal text across (the SSH layer shell-quotes the tmux argv so it survives the
hop intact).

# `$(hostname)` runs in the pane, so it prints the *target's* hostname,
# not the server's:
tmux_send_keys("work", text="echo $(hostname)", enter=True)

If you need a value from the server side instead, interpolate it yourself before
calling send_keys.

Configuration

Optional TOML at ~/.config/mcp-tmux/config.toml (override with
MCP_TMUX_CONFIG):

# toolsets = ["core", "automation"]   # which tool groups to load; ["all"] = full
#                                      # (also via MCP_TMUX_TOOLSETS, env wins)

[defaults]
timeout = 15                 # seconds per tmux invocation
# socket_name = "work"       # default `tmux -L`
# socket_path = "/tmp/sock"  # default `tmux -S`

[targets.prod]
host = "user@prod-db"
ssh_options = ["-J", "bastion", "-p", "2222"]
# socket_name = "work"

With no config file the server still works against local tmux and any ad-hoc
user@host target (SSH options come from your ~/.ssh/config).

Development

python -m venv .venv && . .venv/bin/activate
pip install -e ".[dev]"
pytest            # unit tests always run; integration tests run if tmux exists

See CONTRIBUTING.md for the full checklist (ruff, mypy,
pytest) and contribution guidelines.

Contributing

Bug reports, feature requests, and pull requests are welcome on GitHub:
https://github.com/laszlopere/mcp-tmux. Please read
CONTRIBUTING.md first.

Sponsor

If this project is useful to you, consider sponsoring its development via
GitHub Sponsors. ❤️

License

MIT © László Pere