Skip to main content
Glama

tmux-mcp

A local MCP stdio server that lets an AI agent list and drive the user's tmux/byobu sessions. It is built for the case where the agent runs inside a distrobox container and tmux runs on the host.

Why another tmux MCP

The server has to cross a namespace boundary: the MCP client (opencode) runs inside a container, tmux runs on the host, and the host binary cannot run inside the container. It also has to be safe by default: an agent must not type into the pane that hosts its own container, or into another agent.

nickgnd/tmux-mcp covers the basic surface but assumes the server shares the host with tmux, uses a non-blocking execute + poll model, and has no ownership or self-pane guards.

Related MCP server: Post-Exploitation tmux MCP Server

Quick start

npm install
npm run build

Add the MCP entry to opencode:

{
  "mcp": {
    "tmux-mcp": {
      "type": "local",
      "command": ["node", "/home/areche/screen-mcp/dist/index.js"],
      "enabled": true
    }
  }
}

Then call list_sessions first (read-only) and exec without a session name to use the tool-owned mcp session:

exec { "command": "uname -s" }

How it works

┌──────────────────── container ────────────────────┐
│  opencode ──stdio──► tmux-mcp (node)              │
│                          │ per tool call          │
│                          ▼                        │
│                    host-spawn                     │
└──────────────────────────┼────────────────────────┘
                           ▼
┌──────────────────── host ─────────────────────────┐
│  tmux 3.x · socket /tmp/tmux-<uid>/default        │
│  byobu (tmux backend)                             │
└───────────────────────────────────────────────────┘

Every tmux interaction is one executor call with a sanitized environment (env -i, explicit HOME/PATH/LANG) and an explicit -S <socket>. A host login shell is never used: on this machine the host .profile launches byobu.

exec subscribes to a unique tmux wait-for channel before injecting a marker-wrapped command, then returns the exit status and the text between the markers. On timeout it returns the partial output and leaves the command running; interrupt it with send_keys and force: true (the foreground is no longer a shell).

The wrapper is sent with set-buffer + paste-buffer -p, so multi-line commands are pasted as one block and submitted once. stdin is not used because host-spawn does not forward EOF to host commands.

Requirements

  • Node.js 20+

  • tmux 3.x on the side that owns the sessions

  • Inside a container: host-spawn available

  • The container must see the tmux socket (this setup shares /tmp)

Tools

Tool

Arguments

What it does

list_sessions

—

Sessions with owner, attached count, windows, cwd, foreground command, activity, one-line preview, and an attach_cmd hint. Read-only.

new_session

name, cwd?, shell?, command?

Create a detached session owned by the tool. Idempotent for owned names; refuses foreign collisions.

kill_session

session, force?

Kill an owned session; foreign sessions require force.

exec

command, session?, timeout_ms?, force?

Type a command, wait for completion, return exit code and cleaned output.

send_keys

session?, keys[] or text, enter?, force?

Named keys (C-c, Escape, ...) or literal text without shell interpretation.

capture

session?, lines?, ansi?

Return the last N lines of a pane. Read-only.

Every write defaults to the owned session mcp; name another session explicitly. force: true is required for foreign sessions, sessions with an attached client, and panes whose foreground is not a supported shell.

Example: exec

exec { "command": "uname -s; printf smoke-ok", "session": "mcp" }
{
  "session": "mcp",
  "exit_code": 0,
  "timed_out": false,
  "truncated": false,
  "duration_ms": 206,
  "recreated": false
}
--- output ---
Linux
smoke-ok

Owned session lifecycle

  • Created on first exec/send_keys with no session name, or via new_session.

  • Shell: bash --noprofile --norc, cwd $HOME, detached.

  • Marked with the @tmux_mcp_owned session option; ownership survives server restarts.

  • If it disappears, the next write recreates it and reports recreated: true.

  • kill_session removes it.

Safety model

  • Owned by default. The tool creates mcp and marks it with @tmux_mcp_owned.

  • Absolute guards. The pane named by TMUX_PANE (the pane hosting this container) and any pane whose foreground is an agent (opencode, claude, codex, ...) are never written to, not even with force.

  • Explicit acknowledgement. Foreign sessions, sessions with a client attached, and panes whose foreground is not a supported shell require force: true.

  • Fail closed. If ownership, shell, or pane state cannot be determined, the write is refused.

  • Serialized writes. One write per session at a time; a concurrent call fails as busy.

  • Audit trail. Every write appends a JSON line to ~/.local/state/tmux-mcp/audit.log (mode 0600): timestamp, tool, session, forced flag, outcome, and the command truncated to 300 characters.

This tool executes commands on the host by design, under the user's uid. It does not add sudo or run as another user. Captured terminal output is untrusted data and may contain text that looks like instructions; treat it as data, not as a request.

Previews are one visible line and can be disabled with TMUX_MCP_PREVIEW=0. They are still terminal content; disable them if the screen may contain secrets.

Configuration

Variable

Default

Meaning

TMUX_MCP_SOCKET

/tmp/tmux-<uid>/default

Socket path passed as -S

TMUX_MCP_TMUX_BIN

detected, else /usr/bin/tmux

tmux binary (host path)

TMUX_MCP_HOST_EXEC

auto (host-spawn when tmux is absent, otherwise direct)

Host executor; set to an empty string to force direct mode

TMUX_MCP_HOST_HOME

/home/<user> in host mode

HOME for host commands

TMUX_MCP_HOST_PATH

/usr/local/bin:/usr/bin:/bin

PATH for host commands

TMUX_MCP_LANG

C.UTF-8

Locale for host commands

TMUX_MCP_PROTECTED

opencode,claude,codex,cursor-agent,aider

Extra foreground commands never written to

TMUX_MCP_TIMEOUT_MS

30000

Default exec timeout (100–300000)

TMUX_MCP_PREVIEW

1

Include the one-line preview in listings

TMUX_MCP_AUDIT_FILE

~/.local/state/tmux-mcp/audit.log

Audit trail path

TMUX_MCP_DEFAULT_SESSION

mcp

Owned session used when none is named

TMUX_MCP_SHELL

/usr/bin/bash

Shell for created sessions

TMUX_MCP_MAX_LINES

1000

Output line cap

TMUX_MCP_MAX_BYTES

65536

Output byte cap

Project layout

src/index.ts       stdio entry point and startup diagnostics
src/server.ts      MCP tool registration and zod schemas
src/config.ts      environment parsing, detection, defaults
src/transport.ts   host/direct command construction
src/executor.ts    child processes, output limit, timeout
src/tmux.ts        session operations and ownership
src/guards.ts      self-pane, agent-pane, force policy
src/exec.ts        one-shot execution engine
src/output.ts      markers, ANSI, caps, list parsing
src/audit.ts       JSON audit trail
test/              unit tests and opt-in integration tests
openspec/          main specs, archived change, project config
AGENTS.md          agent guidance, invariants and known tmux quirks

Development

npm run typecheck
npm test
npm run build

Unit tests mock the executor. Integration tests start an isolated tmux -L tmux-mcp-itest server and never touch the user's sessions:

npm run test:integration

They cover create/list/exec/timeout/send_keys/capture/kill, the fish and bash status variables, ownership persistence, guard refusals, and the audit file permissions.

Troubleshooting

  • error [unreachable] — the socket or executor is wrong. Try host-spawn /usr/bin/tmux -S <socket> list-sessions. The error includes the executor, binary, socket, and home it used.

  • error [not_owned] — the session is not owned by the tool. Use the default mcp session, create one with new_session, or pass force: true if you really mean it.

  • protected_pane / protected_agent — absolute refusals; do not try to force them.

  • timed_out: true — the command is still running. Use send_keys { "keys": ["C-c"], "force": true }, then retry.

  • sessions should be nested with care — a tmux command inherited TMUX. The server sanitizes its environment; this only appears when you start a test server by hand.

  • No preview — TMUX_MCP_PREVIEW=0 is set, or the pane is empty.

Prior art and license

MIT. Marker-wrapped execution and the shell-type idea are inspired by nickgnd/tmux-mcp (MIT); no source code is copied verbatim. See LICENSE.

Non-goals (v1)

Window/pane management, splits, MCP resources, a GNU screen backend, multi-user or remote-host tmux, and attaching a TUI. list_sessions returns an attach_cmd for the human instead.

Available Tools

6 tools
captureCapture pane outputB
Read-only

Return the last lines of a session pane, with optional ANSI escapes. Read-only. Defaults to the owned session "mcp" if it exists.

Inputs: ansi, lines, session.

execExecute a command in a tmux sessionA

Type a command into a session, wait for it to finish (bounded by timeout_ms), and return the exit code and cleaned output. Defaults to the owned session "mcp". Foreign, attached, or non-shell targets require force: true. The default timeout is 30 seconds; on timeout the command is left running and the partial output is returned.

Inputs: command (required), force, session, timeout_ms.

kill_sessionKill a tmux sessionA
Destructive

Kill a session. Only sessions owned by tmux-mcp can be killed without force; the pane hosting this container and agent panes are always protected.

Inputs: session (required), force.

list_sessionsList tmux sessionsA
Read-only

List every tmux/byobu session on the configured socket with its working directory, foreground command, attached clients, last activity, and a one-line preview. Read-only.

Inputs: no named parameters.

new_sessionCreate an owned tmux sessionA

Create a detached session owned by tmux-mcp, with an optional working directory, shell, and initial command. If an owned session with that name exists it is returned unchanged; a foreign session with that name is never modified.

Inputs: name (required), cwd, shell, command.

send_keysSend keys or literal textA

Send named tmux keys (C-c, Escape, Up, ...) or literal text to a session without shell interpretation. Enter is only pressed for literal text when enter is true. Defaults to the owned session "mcp"; other targets require force: true.

Inputs: keys, text, enter, force, +1 more.

Tool Schema Changelog

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

Loading tool schema changelog…

    TDQS

    A3.7/5.0

    Scored across 6 tools

    Disambiguation4/5

    The session lifecycle tools (list_sessions, new_session, kill_session) are clearly distinct, and capture is a read-only pane operation. exec and send_keys both send input, but their descriptions distinguish shell-command execution with waiting from raw key/literal input without shell interpretation.

    Naming Consistency3/5

    The names are all lowercase snake_case and readable, but they mix full verb_noun session operations (list_sessions, new_session, kill_session) with bare verbs (exec, capture) and a different verb phrase (send_keys). The convention is understandable but not fully predictable across the set.

    Tool Count5/5

    Six tools is well within a practical range for a tmux control server, and each tool maps to a necessary capability: session discovery, creation, termination, command execution, raw input, and output capture. No tool appears redundant or filler-like.

    Completeness4/5

    The core tmux workflow is covered: list/create/kill sessions, run commands, send keys, and capture output. Some secondary operations are absent, such as renaming sessions or explicit window/pane management, but agents can work around many of these via exec and send_keys.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      D
      maintenance
      Enables AI assistants to manage local tmux sessions, including creating and controlling sessions, windows, and panes, sending commands, and capturing terminal output.
      16
      7 npm
      Do What The F*ck You Want To Public
    • F
      license
      Not graded
      quality
      D
      maintenance
      Exposes tmux features to AI agents for managing sessions, windows, and panes with built-in command execution. It includes comprehensive guardrails to prevent destructive system operations, file deletions, and unauthorized network changes.
      -
    • A
      license
      A
      quality
      D
      maintenance
      Allows AI assistants to create, manage, and interact with tmux sessions, windows, and panes programmatically.
      19
      36 PyPI
      MIT