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.

With uvx installed:

$ claude mcp add libtmux -- uvx libtmux-mcp

With pipx installed:

$ claude mcp add libtmux -- pipx run libtmux-mcp

Install the packages first:

$ pip install --user --upgrade libtmux libtmux-mcp

Then register:

$ claude mcp add libtmux -- libtmux-mcp

With uvx installed:

{
    "mcpServers": {
        "libtmux": {
            "command": "uvx",
            "args": ["libtmux-mcp"]
        }
    }
}

With pipx installed:

{
    "mcpServers": {
        "libtmux": {
            "command": "pipx",
            "args": ["run", "libtmux-mcp"]
        }
    }
}

Install the packages first:

$ pip install --user --upgrade libtmux libtmux-mcp

Then use this config:

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

With uvx installed:

$ codex mcp add libtmux -- uvx libtmux-mcp

With pipx installed:

$ codex mcp add libtmux -- pipx run libtmux-mcp

Install the packages first:

$ pip install --user --upgrade libtmux libtmux-mcp

Then register:

$ codex mcp add libtmux -- libtmux-mcp

With uvx installed:

$ gemini mcp add libtmux uvx -- libtmux-mcp

With pipx installed:

$ gemini mcp add libtmux pipx -- run libtmux-mcp

Install the packages first:

$ pip install --user --upgrade libtmux libtmux-mcp

Then register:

$ gemini mcp add libtmux libtmux-mcp

With uvx installed:

{
    "mcpServers": {
        "libtmux": {
            "command": "uvx",
            "args": ["libtmux-mcp"]
        }
    }
}

With pipx installed:

{
    "mcpServers": {
        "libtmux": {
            "command": "pipx",
            "args": ["run", "libtmux-mcp"]
        }
    }
}

Install the packages first:

$ pip install --user --upgrade libtmux libtmux-mcp

Then use this config:

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

Quickstart

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

Quickstart

Tools

Every tool, grouped by intent and safety tier.

Tools

Prompts

Four workflow recipes the client renders for the model.

Prompts

Resources

Snapshot views of the tmux hierarchy via tmux:// URIs.

Resources

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 · snapshot_pane · get_pane_info · search_panes · wait_for_text · wait_for_content_change · display_message

Act mutating¶

Create or modify tmux objects.

create_session · send_keys · paste_text · create_window · split_window · select_pane · select_window · move_window · resize_pane · pipe_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