libtmux-mcp

Terminal control for AI agents, built on libtmux and FastMCP.

This server maps tmux’s object hierarchy — sessions, windows, panes — into MCP tools grouped by the operation they request. The server enforces the selected groups at the MCP tool boundary.

[!warning] Warning Pre-alpha. APIs may change. Feedback welcome.

With uvx installed:

$ claude mcp add tmux -- uvx libtmux-mcp

---

Quickstart

Quickstart

Tools

Tools

Prompts

Prompts

Resources

Resources

Trust model

Trust model

Client setup

MCP Clients

---

What you can do

Inspect inspect

Request tmux state and terminal output.

list_sessions · capture_pane · capture_since · snapshot_pane · get_pane_info · find_pane_by_position · search_panes · wait_for_text · display_message · call_read_tools_batch

Manage manage

Change tmux structure or presentation.

rename_session · resize_pane · select_layout · select_pane · move_window · enter_copy_mode · load_buffer · wait_for_channel

Execute execute

Start or drive pane processes, or store state that can control later execution.

create_session · create_window · split_window · respawn_pane · send_keys · send_keys_batch · run_command · paste_text · paste_buffer · pipe_pane · set_option · set_environment

Teardown teardown

Delete tmux objects or retained scrollback. Not reversible.

clear_pane · kill_session · kill_window · kill_pane · kill_server · delete_buffer

Example: keep test runs out of persistent history

libtmux-mcp provides best-effort history suppression for Bash, Zsh, and Fish. MCP calls to run_command use lightweight command suppression by default. When you create a new shell, opt into stronger no-disk controls with suppress_persistent_history=true.

[!note] Prompt Create a tmux session called “checks” with best-effort no-disk shell-history controls, run pytest -q in its initial pane, and show me the result.

The agent calls create_session with suppress_persistent_history=true, reuses active_pane_id from the returned SessionInfo, and calls run_command without an override. The same spawn option on create_window, split_window, or respawn_pane applies only to the process that call starts.

These controls reduce history noise; they do not make commands secret. See History suppression for shell-specific behavior, Configuration for the server default, and Trust model for other observation surfaces.

Browse all tools →

---

Mental model

• Object hierarchy — sessions contain windows, windows contain panes (Concepts)
• Toolsets — inspect, manage, execute, teardown; what each groups (Trust model)
• tmux is the source of truth — the server reads from it and writes to it, never caches or abstracts

---