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. Some tools read state. Some mutate it. Some destroy. The distinction is explicit and enforced.

Warning

Pre-alpha. APIs may change. Feedback welcome.

Quickstart

Install, connect, get a first result. Under 2 minutes.

Quickstart
Tools

Every tool, grouped by intent and safety tier.

Tools
Safety tiers

Readonly, mutating, destructive. Know what changes state.

Safety tiers
Client setup

Config blocks for Claude Desktop, Claude Code, Cursor, and others.

MCP Clients

What you can do

Inspect readonly

Read tmux state without changing anything.

list_sessions · capture_pane · get_pane_info · search_panes · wait_for_text

Act mutating

Create or modify tmux objects.

create_session · send_keys · create_window · split_window · resize_pane · set_option

Destroy destructive

Tear down tmux objects. Not reversible.

kill_session · kill_window · kill_pane · kill_server

Browse all tools →

Mental model

  • Object hierarchy — sessions contain windows, windows contain panes (Concepts)

  • Read vs. mutate — some tools observe, some act, some destroy (Safety tiers)

  • tmux is the source of truth — the server reads from it and writes to it, never caches or abstracts