Skip to main content
Glama
Sign In
tmux-mcp

tmux-mcp

by vn-lazyming
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

tmux-mcp

A small MCP server that lets an your agent run commands interactively, not in one-shot mode, in a live tmux pane that you can watch and type in too.

It is not limited to one session: the agent can list every tmux session, window and pane on the machine, create sessions with any name, and send keys to or read from any pane, including your own.

Tools

  • tmux_send: type or paste text and keys into any pane

  • tmux_read: read what's on any pane

  • tmux_list_panes: list all sessions, windows and panes

  • tmux_new: open a session, window or pane with a name you choose

  • tmux_move: move a pane the agent opened next to another one, e.g. yours

  • tmux_kill: close one that the agent opened

Related MCP server: mcp-interactive-terminal

Setup

Needs uv and tmux.

git clone https://github.com/vn-lazyming/tmux-mcp
cd tmux-mcp && uv sync
claude mcp add tmux -- uv run --directory "$PWD" server.py

Watch what the agent does:

tmux attach -t agent

The session name defaults to agent. Change it with the TMUX_MCP_SESSION env var.

Develop

make dev    # install dev tools
make lint   # ruff format --check, ruff check, ty
make test   # self-check on a private tmux server

License

MIT

Available Tools

6 tools
tmux_killClose terminalA
DestructiveIdempotent

Close a session, window or pane that tmux_new opened, killing whatever runs in it. Refuses anything else, so the human's own panes are never closed.

Inputs: name (required). Returns: result

tmux_list_panesList terminal panesA
Read-onlyIdempotent

List every tmux session, window and pane as target pane_id command cwd [flags]. Pass either id to tmux_send/tmux_read to work in the human's own pane. [opened by agent: KIND NAME] marks what tmux_new opened; tmux_kill(NAME) closes it.

Inputs: no named parameters. Returns: result

tmux_moveMove terminal paneA

Move a pane tmux_new opened into the window of target_pane, splitting it, so the human sees both at once. Their view does not switch to it. Whatever runs in the pane keeps running. Leaving a session or window empty closes it.

Inputs: name (required), target_pane. Returns: result

tmux_newOpen terminalA

Open a new tmux session, window or pane without switching the human's view.

Returns its pane id (e.g. "%7") for tmux_send/tmux_read: unlike "ming:0.1" it stays on this pane when the human renames the session or splits the window.

Inputs: name (required), cwd, kind, session. Returns: result

tmux_readRead terminalA
Read-onlyIdempotent

Return the pane's last lines lines (what the human sees, plus scrollback), optionally waiting first. Last line: [at shell prompt] or [foreground: X], plus [timeout: ...] if the wait gave up.

Inputs: lines, timeout, wait_for, wait_done, +1 more. Returns: result

tmux_sendType into terminalA
Destructive

Type into the live pane like a human, then return the output that appeared. Prefer this over a one-shot shell for anything interactive or stateful.

Returns once it is finished (shell prompt back, or a REPL/gdb/ssh showing the same prompt line as before), or the screen has been quiet idle seconds, or timeout passes. The last line says the state: [at shell prompt] = done; [foreground: X] = X still running or a REPL waiting for input. If it is still running, call tmux_read(wait_done=True) to wait for it to finish.

Inputs: idle, keys, text, enter, +3 more. Returns: result

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Deploy Server
    One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

    TDQS

    A4.2/5.0

    Scored across 6 tools

    Disambiguation4/5

    The tools have mostly distinct purposes: send writes to a pane, read inspects one, list enumerates panes, new creates one, move relocates one, and kill closes one. There is some conceptual overlap between tmux_send and tmux_read because both can return pane output and tmux_send may wait for completion, but the descriptions make the intended usage boundaries clear.

    Naming Consistency5/5

    All six tools use the same tmux_ prefix followed by a concise verb or verb-noun style: tmux_send, tmux_read, tmux_new, tmux_move, tmux_kill, tmux_list_panes. The naming is predictable and consistent throughout.

    Tool Count5/5

    Six tools is a well-scoped surface for controlling and inspecting tmux panes without excessive granularity. Each tool covers a distinct operation and there are no obvious redundant tools.

    Completeness4/5

    The set covers the core tmux lifecycle agents need: discovery, creation, interaction, reading output, moving panes, and cleanup. Minor gaps exist around session/window management details and things like renaming or resizing, but these are not essential for the stated interactive-pane workflow.

    Resources

    Related MCP Connectors

    Related MCP Servers

    • mcp-ssh-interactive

      qnxqnxqnx
      A
      license
      Not graded
      quality
      D
      maintenance
      MCP server that enables AI agents to run fully interactive SSH sessions (via tmux) and execute commands like a human operator, with persistent sessions and multiple concurrent connections.
      6
      MIT