@fr1sk/tmux-mcp

tmux-mcp

MCP server that gives AI assistants full visibility into your tmux sessions — browse sessions, windows, and panes, read terminal output, and send commands.

Watch your AI agent work in real-time. Enable TMUX_MCP_ALWAYS_USE to force every shell command through a named tmux session instead of direct Bash — every command your AI runs appears live in your terminal, fully auditable.

Works with Claude Code, OpenCode, Cursor, Windsurf, and any MCP-compatible host.

What it can do

Read your terminal state

• List every active tmux session with window count, creation time, and attached status
• List windows inside a session — index, name, pane count, which one is active
• List panes inside a window — size, running command, which one is active

See what's on screen

• Capture the visible output of any pane — up to 5 000 lines of scrollback
• Read logs, compiler errors, server output, test runs — anything in your terminal

Create and organise

• Create sessions, windows, and panes with a working directory and an initial command
• Split panes horizontally or vertically
• Rename sessions and windows for reliable targeting

Clean up

• Kill sessions, windows, or individual panes

Control panes

• Send shell commands to any pane and immediately read the output
• Send raw key sequences: C-c to interrupt, Escape to exit, arrow keys, etc.
• Configurable wait time before capturing so long-running commands have time to finish

Error-safe

• Bad target? No tmux server? Returns a readable error message instead of crashing

Tools

list_sessions

Lists all active tmux sessions. No parameters.

Returns: session name, number of windows, creation time, attached/detached status.

list_windows

Lists windows inside a session.

Parameter	Type	Description
session	string	Session name (from list_sessions)

Returns: window index, name, pane count, whether it's the active window.

list_panes

Lists panes inside a session or window.

Parameter	Type	Description
target	string	Session name (work) or session:window (work:0)

Returns: pane index, title, dimensions (e.g. 220x50), whether it's active, running command.

capture_pane

Captures the current terminal output of a pane.

Parameter	Type	Default	Description
target	string	—	Pane target: session:window.pane (e.g. work:0.0)
lines	number	150	Lines of scrollback to include (max 5000)

Returns: raw terminal text as it appears on screen.

Security note: pane output can contain environment variables, API keys, tokens, and credentials if they were printed to the terminal. Only use this server in trusted local environments.

send_keys

Sends a command or key sequence to a pane and captures the result.

Parameter	Type	Default	Description
target	string	—	Pane target: session:window.pane
keys	string	—	Command or tmux key notation (C-c, Escape, Up, etc.)
enter	boolean	true	Press Enter after the keys
capture_lines	number	50	Lines to capture after sending
wait_ms	number	400	Milliseconds to wait before capturing

Returns: confirmation + pane output after the command ran.

new_session

Creates a new detached tmux session.

Parameter	Type	Description
name	string	Session name. Omit to let tmux auto-assign one.
cwd	string	Working directory for the session.
command	string	Shell command to run immediately in the first window.

new_window

Creates a new window inside an existing session.

Parameter	Type	Description
session	string	Session to create the window in.
name	string	Window name.
cwd	string	Working directory for the new window.
command	string	Shell command to run immediately.

split_pane

Splits a pane into two.

Parameter	Type	Default	Description
target	string	—	Pane or window to split: session:window.pane
direction	horizontal | vertical	horizontal	horizontal = left/right split, vertical = top/bottom
cwd	string	—	Working directory for the new pane.
command	string	—	Shell command to run in the new pane.
size	number	—	Size of the new pane as a percentage (1–99).

kill_session

Kills a session and all its windows and panes. Destructive — cannot be undone.

Parameter	Type	Description
session	string	Session name to kill.

kill_window

Kills a window and all its panes. Destructive.

Parameter	Type	Description
target	string	Window target: session:window

kill_pane

Kills a single pane and its running process. Destructive.

Parameter	Type	Description
target	string	Pane target: session:window.pane

rename_session

Parameter	Type	Description
session	string	Current session name.
new_name	string	New name.

rename_window

Parameter	Type	Description
target	string	Window target: session:window
new_name	string	New name.

Target format

All tools use tmux's standard session:window.pane notation:

work           →  session named "work"
work:0         →  window 0 of session "work"
work:0.0       →  pane 0, window 0, session "work"
work:editor.1  →  pane 1 of window named "editor" in session "work"

Use list_sessions → list_windows → list_panes to discover the right target before calling capture_pane or send_keys.

Install

npm install -g @fr1sk/tmux-mcp

Configure

OpenCode (~/.config/opencode/opencode.json)

{
  "mcp": {
    "tmux": {
      "type": "local",
      "command": ["tmux-mcp"]
    }
  }
}

Claude Code (~/.claude/settings.json)

{
  "mcpServers": {
    "tmux": {
      "command": "tmux-mcp"
    }
  }
}

Cursor / Windsurf (mcp.json)

{
  "mcpServers": {
    "tmux": {
      "command": "tmux-mcp"
    }
  }
}

Usage examples

What tmux sessions do I have running?

Show me the output of my dev server — it's in the work session

My tests are failing, check what's in work:1.0

Run git status in my work session and show me the output

Send Ctrl-C to work:0.0, the process is stuck

Tail the last 300 lines from the logs pane in my api session

Create a new session called 'dev' in ~/Projects/myapp and run npm run dev

Split work:0.0 vertically and run npm test in the new pane

Rename session 'new' to 'api'

Kill the old session named 'temp'

Environment variables

Set these in your MCP client config under environment to control agent behavior.

Variable	Default	Description
TMUX_MCP_DEFAULT_SESSION	—	Session name the agent routes commands to when alwaysUseTmux is on
TMUX_MCP_ALWAYS_USE	false	Set to "true" to route all shell commands through tmux instead of direct Bash

When both are set, the get_config tool returns an instructions field the agent uses to automatically route every shell command through send_keys in the configured session.

Example (OpenCode):

{
  "mcp": {
    "tmux": {
      "type": "local",
      "command": ["tmux-mcp"],
      "environment": {
        "TMUX_MCP_ALWAYS_USE": "true",
        "TMUX_MCP_DEFAULT_SESSION": "dev"
      }
    }
  }
}

Security

This server provides unrestricted local shell access through tmux:

• capture_pane — returns raw terminal output, which may include environment variables, API keys, tokens, database passwords, and SSH private keys if they were printed to the terminal.
• send_keys — executes arbitrary shell commands in the target pane. Any command the AI sends runs in your shell with your permissions.
• command parameter on new_session, new_window, and split_pane — passed directly to tmux, which runs it via $SHELL -c. No validation or sandboxing.

Only use this server in trusted local development environments. Never expose it to network-accessible MCP hosts or untrusted AI assistants.

Requirements

• Node.js 18+
• tmux on $PATH