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

Pre-alpha. APIs may change. Feedback welcome.

With uvx installed:

$ claude mcp add tmux -- uvx libtmux-mcp

With uvx installed:

$ claude mcp add tmux -- uvx --exclude-newer P7D --exclude-newer-package libtmux-mcp=2099-01-01 libtmux-mcp

With uvx installed:

$ claude mcp add tmux -- uvx --no-config libtmux-mcp

With uvx installed:

$ claude mcp add tmux --scope user -- uvx libtmux-mcp

With uvx installed:

$ claude mcp add tmux --scope user -- uvx --exclude-newer P7D --exclude-newer-package libtmux-mcp=2099-01-01 libtmux-mcp

With uvx installed:

$ claude mcp add tmux --scope user -- uvx --no-config libtmux-mcp

With uvx installed:

$ claude mcp add tmux --scope project -- uvx libtmux-mcp

With uvx installed:

$ claude mcp add tmux --scope project -- uvx --exclude-newer P7D --exclude-newer-package libtmux-mcp=2099-01-01 libtmux-mcp

With uvx installed:

$ claude mcp add tmux --scope project -- uvx --no-config libtmux-mcp

With pipx installed:

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

With pipx installed:

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

pip has no per-package cooldown override, so this snippet runs without cooldown enforcement. Switch to the uvx tab — it applies the cooldown to transitive deps via `--exclude-newer` while exempting libtmux-mcp itself via `--exclude-newer-package`.

With pipx installed:

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

With pipx installed:

$ claude mcp add tmux --scope user -- pipx run libtmux-mcp

With pipx installed:

$ claude mcp add tmux --scope user -- pipx run libtmux-mcp

With pipx installed:

$ claude mcp add tmux --scope user -- pipx run libtmux-mcp

With pipx installed:

$ claude mcp add tmux --scope project -- pipx run libtmux-mcp

With pipx installed:

$ claude mcp add tmux --scope project -- pipx run libtmux-mcp

With pipx installed:

$ claude mcp add tmux --scope project -- pipx run libtmux-mcp

Install the packages first:

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

Then register:

$ claude mcp add tmux -- libtmux-mcp

Install the packages first:

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

Then register:

$ claude mcp add tmux -- libtmux-mcp

Install the packages first:

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

Then register:

$ claude mcp add tmux -- libtmux-mcp

Install the packages first:

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

Then register:

$ claude mcp add tmux --scope user -- libtmux-mcp

Install the packages first:

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

Then register:

$ claude mcp add tmux --scope user -- libtmux-mcp

Install the packages first:

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

Then register:

$ claude mcp add tmux --scope user -- libtmux-mcp

Install the packages first:

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

Then register:

$ claude mcp add tmux --scope project -- libtmux-mcp

Install the packages first:

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

Then register:

$ claude mcp add tmux --scope project -- libtmux-mcp

Install the packages first:

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

Then register:

$ claude mcp add tmux --scope project -- libtmux-mcp

With uvx installed:

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

Config file: claude_desktop_config.json

With uvx installed:

{
    "mcpServers": {
        "tmux": {
            "command": "uvx",
            "args": ["--exclude-newer", "P7D", "--exclude-newer-package", "libtmux-mcp=2099-01-01", "libtmux-mcp"]
        }
    }
}

Config file: claude_desktop_config.json

With uvx installed:

{
    "mcpServers": {
        "tmux": {
            "command": "uvx",
            "args": ["libtmux-mcp"],
            "env": { "UV_NO_CONFIG": "1" }
        }
    }
}

Config file: claude_desktop_config.json

With pipx installed:

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

Config file: claude_desktop_config.json

With pipx installed:

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

Config file: claude_desktop_config.json

With pipx installed:

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

Config file: claude_desktop_config.json

Install the packages first:

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

Then use this config:

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

Config file: claude_desktop_config.json

Install the packages first:

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

Then use this config:

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

Config file: claude_desktop_config.json

Install the packages first:

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

Then use this config:

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

Config file: claude_desktop_config.json

With uvx installed:

$ codex mcp add tmux -- uvx libtmux-mcp

With uvx installed:

$ codex mcp add tmux -- uvx --exclude-newer P7D --exclude-newer-package libtmux-mcp=2099-01-01 libtmux-mcp

With uvx installed:

$ codex mcp add tmux -- uvx --no-config libtmux-mcp

With uvx installed:

Codex's CLI doesn't support project scope yet — paste this into .codex/config.toml at the repo root.

[mcp_servers.tmux]
command = "uvx"
args = ["libtmux-mcp"]

With uvx installed:

Codex's CLI doesn't support project scope yet — paste this into .codex/config.toml at the repo root.

[mcp_servers.tmux]
command = "uvx"
args = ["--exclude-newer", "P7D", "--exclude-newer-package", "libtmux-mcp=2099-01-01", "libtmux-mcp"]

With uvx installed:

Codex's CLI doesn't support project scope yet — paste this into .codex/config.toml at the repo root.

[mcp_servers.tmux]
command = "uvx"
args = ["libtmux-mcp"]
env = { UV_NO_CONFIG = "1" }

With pipx installed:

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

With pipx installed:

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

With pipx installed:

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

With pipx installed:

Codex's CLI doesn't support project scope yet — paste this into .codex/config.toml at the repo root.

[mcp_servers.tmux]
command = "pipx"
args = ["run", "libtmux-mcp"]

With pipx installed:

Codex's CLI doesn't support project scope yet — paste this into .codex/config.toml at the repo root.

[mcp_servers.tmux]
command = "pipx"
args = ["run", "libtmux-mcp"]

With pipx installed:

Codex's CLI doesn't support project scope yet — paste this into .codex/config.toml at the repo root.

[mcp_servers.tmux]
command = "pipx"
args = ["run", "libtmux-mcp"]

Install the packages first:

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

Then register:

$ codex mcp add tmux -- libtmux-mcp

Install the packages first:

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

Then register:

$ codex mcp add tmux -- libtmux-mcp

Install the packages first:

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

Then register:

$ codex mcp add tmux -- libtmux-mcp

Install the packages first:

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

Then register:

Codex's CLI doesn't support project scope yet — paste this into .codex/config.toml at the repo root.

[mcp_servers.tmux]
command = "libtmux-mcp"

Install the packages first:

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

Then register:

Codex's CLI doesn't support project scope yet — paste this into .codex/config.toml at the repo root.

[mcp_servers.tmux]
command = "libtmux-mcp"

Install the packages first:

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

Then register:

Codex's CLI doesn't support project scope yet — paste this into .codex/config.toml at the repo root.

[mcp_servers.tmux]
command = "libtmux-mcp"

With uvx installed:

$ gemini mcp add --scope user tmux uvx -- libtmux-mcp

With uvx installed:

$ gemini mcp add --scope user tmux uvx -- --exclude-newer P7D --exclude-newer-package libtmux-mcp=2099-01-01 libtmux-mcp

With uvx installed:

$ gemini mcp add --scope user tmux uvx -- --no-config libtmux-mcp

With uvx installed:

$ gemini mcp add --scope project tmux uvx -- libtmux-mcp

With uvx installed:

$ gemini mcp add --scope project tmux uvx -- --exclude-newer P7D --exclude-newer-package libtmux-mcp=2099-01-01 libtmux-mcp

With uvx installed:

$ gemini mcp add --scope project tmux uvx -- --no-config libtmux-mcp

With pipx installed:

$ gemini mcp add --scope user tmux pipx -- run libtmux-mcp

With pipx installed:

$ gemini mcp add --scope user tmux pipx -- run libtmux-mcp

With pipx installed:

$ gemini mcp add --scope user tmux pipx -- run libtmux-mcp

With pipx installed:

$ gemini mcp add --scope project tmux pipx -- run libtmux-mcp

With pipx installed:

$ gemini mcp add --scope project tmux pipx -- run libtmux-mcp

With pipx installed:

$ gemini mcp add --scope project tmux pipx -- run libtmux-mcp

Install the packages first:

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

Then register:

$ gemini mcp add --scope user tmux libtmux-mcp

Install the packages first:

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

Then register:

$ gemini mcp add --scope user tmux libtmux-mcp

Install the packages first:

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

Then register:

$ gemini mcp add --scope user tmux libtmux-mcp

Install the packages first:

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

Then register:

$ gemini mcp add --scope project tmux libtmux-mcp

Install the packages first:

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

Then register:

$ gemini mcp add --scope project tmux libtmux-mcp

Install the packages first:

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

Then register:

$ gemini mcp add --scope project tmux libtmux-mcp

With uvx installed:

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

Config file: .cursor/mcp.json (in repo)

With uvx installed:

{
    "mcpServers": {
        "tmux": {
            "command": "uvx",
            "args": ["--exclude-newer", "P7D", "--exclude-newer-package", "libtmux-mcp=2099-01-01", "libtmux-mcp"]
        }
    }
}

Config file: .cursor/mcp.json (in repo)

With uvx installed:

{
    "mcpServers": {
        "tmux": {
            "command": "uvx",
            "args": ["libtmux-mcp"],
            "env": { "UV_NO_CONFIG": "1" }
        }
    }
}

Config file: .cursor/mcp.json (in repo)

With uvx installed:

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

Config file: ~/.cursor/mcp.json

With uvx installed:

{
    "mcpServers": {
        "tmux": {
            "command": "uvx",
            "args": ["--exclude-newer", "P7D", "--exclude-newer-package", "libtmux-mcp=2099-01-01", "libtmux-mcp"]
        }
    }
}

Config file: ~/.cursor/mcp.json

With uvx installed:

{
    "mcpServers": {
        "tmux": {
            "command": "uvx",
            "args": ["libtmux-mcp"],
            "env": { "UV_NO_CONFIG": "1" }
        }
    }
}

Config file: ~/.cursor/mcp.json

With pipx installed:

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

Config file: .cursor/mcp.json (in repo)

With pipx installed:

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

Config file: .cursor/mcp.json (in repo)

With pipx installed:

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

Config file: .cursor/mcp.json (in repo)

With pipx installed:

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

Config file: ~/.cursor/mcp.json

With pipx installed:

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

Config file: ~/.cursor/mcp.json

With pipx installed:

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

Config file: ~/.cursor/mcp.json

Install the packages first:

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

Then use this config:

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

Config file: .cursor/mcp.json (in repo)

Install the packages first:

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

Then use this config:

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

Config file: .cursor/mcp.json (in repo)

Install the packages first:

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

Then use this config:

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

Config file: .cursor/mcp.json (in repo)

Install the packages first:

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

Then use this config:

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

Config file: ~/.cursor/mcp.json

Install the packages first:

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

Then use this config:

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

Config file: ~/.cursor/mcp.json

Install the packages first:

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

Then use this config:

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

Config file: ~/.cursor/mcp.json

With uvx installed:

$ grok mcp add --scope user tmux -- uvx libtmux-mcp

With uvx installed:

$ grok mcp add --scope user tmux -- uvx --exclude-newer P7D --exclude-newer-package libtmux-mcp=2099-01-01 libtmux-mcp

With uvx installed:

$ grok mcp add --scope user tmux -- uvx --no-config libtmux-mcp

With uvx installed:

$ grok mcp add --scope project tmux -- uvx libtmux-mcp

With uvx installed:

$ grok mcp add --scope project tmux -- uvx --exclude-newer P7D --exclude-newer-package libtmux-mcp=2099-01-01 libtmux-mcp

With uvx installed:

$ grok mcp add --scope project tmux -- uvx --no-config libtmux-mcp

With pipx installed:

$ grok mcp add --scope user tmux -- pipx run libtmux-mcp

With pipx installed:

$ grok mcp add --scope user tmux -- pipx run libtmux-mcp

With pipx installed:

$ grok mcp add --scope user tmux -- pipx run libtmux-mcp

With pipx installed:

$ grok mcp add --scope project tmux -- pipx run libtmux-mcp

With pipx installed:

$ grok mcp add --scope project tmux -- pipx run libtmux-mcp

With pipx installed:

$ grok mcp add --scope project tmux -- pipx run libtmux-mcp

Install the packages first:

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

Then register:

$ grok mcp add --scope user tmux -- libtmux-mcp

Install the packages first:

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

Then register:

$ grok mcp add --scope user tmux -- libtmux-mcp

Install the packages first:

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

Then register:

$ grok mcp add --scope user tmux -- libtmux-mcp

Install the packages first:

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

Then register:

$ grok mcp add --scope project tmux -- libtmux-mcp

Install the packages first:

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

Then register:

$ grok mcp add --scope project tmux -- libtmux-mcp

Install the packages first:

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

Then register:

$ grok mcp add --scope project tmux -- libtmux-mcp

With uvx installed:

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

Config file: ~/.gemini/config/mcp_config.json

With uvx installed:

{
    "mcpServers": {
        "tmux": {
            "command": "uvx",
            "args": ["--exclude-newer", "P7D", "--exclude-newer-package", "libtmux-mcp=2099-01-01", "libtmux-mcp"]
        }
    }
}

Config file: ~/.gemini/config/mcp_config.json

With uvx installed:

{
    "mcpServers": {
        "tmux": {
            "command": "uvx",
            "args": ["libtmux-mcp"],
            "env": { "UV_NO_CONFIG": "1" }
        }
    }
}

Config file: ~/.gemini/config/mcp_config.json

With pipx installed:

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

Config file: ~/.gemini/config/mcp_config.json

With pipx installed:

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

Config file: ~/.gemini/config/mcp_config.json

With pipx installed:

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

Config file: ~/.gemini/config/mcp_config.json

Install the packages first:

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

Then use this config:

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

Config file: ~/.gemini/config/mcp_config.json

Install the packages first:

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

Then use this config:

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

Config file: ~/.gemini/config/mcp_config.json

Install the packages first:

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

Then use this config:

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

Config file: ~/.gemini/config/mcp_config.json

With uvx installed:

$ opencode mcp add tmux -- uvx libtmux-mcp

With uvx installed:

$ opencode mcp add tmux -- uvx --exclude-newer P7D --exclude-newer-package libtmux-mcp=2099-01-01 libtmux-mcp

With uvx installed:

$ opencode mcp add tmux -- uvx --no-config libtmux-mcp

With pipx installed:

$ opencode mcp add tmux -- pipx run libtmux-mcp

With pipx installed:

$ opencode mcp add tmux -- pipx run libtmux-mcp

With pipx installed:

$ opencode mcp add tmux -- pipx run libtmux-mcp

Install the packages first:

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

Then register:

$ opencode mcp add tmux -- libtmux-mcp

Install the packages first:

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

Then register:

$ opencode mcp add tmux -- libtmux-mcp

Install the packages first:

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

Then register:

$ opencode mcp add tmux -- libtmux-mcp

Quickstart

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

Quickstart

Tools

Every tool, grouped by intent and toolset.

Tools

Prompts

Four workflow recipes the client renders for the model.

Prompts

Resources

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

Resources

Trust model

What the toolsets group, and what they do not bound.

Trust model

Client setup

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

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.

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