tmux-mcp
Provides tools for interacting with tmux/byobu sessions on the host, including listing sessions, creating and killing owned sessions, executing commands, sending keys, and capturing pane output, with ownership and safety guards.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@tmux-mcp run uname -s on the host in the mcp tmux session"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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 buildAdd 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-spawnavailableThe container must see the tmux socket (this setup shares
/tmp)
Tools
Tool | Arguments | What it does |
| — | Sessions with owner, attached count, windows, cwd, foreground command, activity, one-line preview, and an |
|
| Create a detached session owned by the tool. Idempotent for owned names; refuses foreign collisions. |
|
| Kill an owned session; foreign sessions require |
|
| Type a command, wait for completion, return exit code and cleaned output. |
|
| Named keys ( |
|
| 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-okOwned session lifecycle
Created on first
exec/send_keyswith no session name, or vianew_session.Shell:
bash --noprofile --norc, cwd$HOME, detached.Marked with the
@tmux_mcp_ownedsession option; ownership survives server restarts.If it disappears, the next write recreates it and reports
recreated: true.kill_sessionremoves it.
Safety model
Owned by default. The tool creates
mcpand 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 withforce.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(mode0600): 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 |
|
| Socket path passed as |
| detected, else | tmux binary (host path) |
| auto ( | Host executor; set to an empty string to force direct mode |
|
|
|
|
|
|
|
| Locale for host commands |
|
| Extra foreground commands never written to |
|
| Default |
|
| Include the one-line preview in listings |
|
| Audit trail path |
|
| Owned session used when none is named |
|
| Shell for created sessions |
|
| Output line cap |
|
| 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 quirksDevelopment
npm run typecheck
npm test
npm run buildUnit 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:integrationThey 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. Tryhost-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 defaultmcpsession, create one withnew_session, or passforce: trueif you really mean it.protected_pane/protected_agent— absolute refusals; do not try to force them.timed_out: true— the command is still running. Usesend_keys { "keys": ["C-c"], "force": true }, then retry.sessions should be nested with care— a tmux command inheritedTMUX. The server sanitizes its environment; this only appears when you start a test server by hand.No preview —
TMUX_MCP_PREVIEW=0is 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 toolscaptureCapture pane outputBRead-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 sessionADestructive
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 sessionsARead-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
Scored across 6 tools
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.
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.
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.
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
Related MCP Connectors
Docs for agent-manager, the terminal UI that runs AI coding agents as live tmux sessions.
Operate Linux, macOS and Windows from your LLM. Every action runs through an auditable allowlist.
Work on your own computers from Claude or ChatGPT: run commands, edit and search files.
Use your Mac, Windows or Linux computer from ChatGPT, Claude or Codex: files, commands, documents.
Related MCP Servers
- AlicenseAqualityDmaintenanceEnables AI assistants to manage local tmux sessions, including creating and controlling sessions, windows, and panes, sending commands, and capturing terminal output.167 npmDo What The F*ck You Want To Public
- FlicenseNot gradedqualityDmaintenanceExposes 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.-
- AlicenseAqualityDmaintenanceAllows AI assistants to create, manage, and interact with tmux sessions, windows, and panes programmatically.1936 PyPIMIT
- AlicenseAqualityDmaintenanceEnables AI agents to spawn, interact with, and orchestrate multiple concurrent terminal sessions via tmux.9MIT