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

... View full README on GitHub