libtmux-mcp server

official

tmux MCP server powered by libtmux

View on git-pull.comTry this MCPSponsored

What can you do with Libtmux MCP?

  • Inspect tmux state — Ask to list_sessions, capture_pane, or search_panes to read current terminal output and session details.
  • Manage windows and panes — Use rename_session, resize_pane, select_layout, or move_window to reorganize your tmux workspace.
  • Execute commands in panes — Run send_keys, run_command, or paste_text to drive processes and interact with running shells.
  • Create and split sessions — Use create_session, create_window, or split_window to set up new tmux layouts for your tasks.
  • Clean up tmux objects — Call kill_session, kill_window, clear_pane, or delete_buffer to tear down sessions and remove scrollback.
  • Suppress shell history — Create sessions with suppress_persistent_history=true to keep test runs out of persistent Bash/Zsh/Fish history.

Documentation

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