MCP Clients¶

Pick your client, install method, and config scope below — the snippet updates accordingly. The scope row appears only for clients with more than one scope (Claude Desktop is always user-level so it has no scope row). The full table of file locations is at the bottom of the page.

With uvx installed:

$ claude mcp add tmux -- uvx libtmux-mcp

Config file: ~/.claude.json (this project)

With uvx installed:

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

Config file: ~/.claude.json (this project)

With uvx installed:

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

Config file: ~/.claude.json (this project)

With uvx installed:

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

Config file: ~/.claude.json (all projects)

With uvx installed:

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

Config file: ~/.claude.json (all projects)

With uvx installed:

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

Config file: ~/.claude.json (all projects)

With uvx installed:

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

Config file: .mcp.json (in repo, version-controlled)

With uvx installed:

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

Config file: .mcp.json (in repo, version-controlled)

With uvx installed:

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

Config file: .mcp.json (in repo, version-controlled)

With pipx installed:

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

Config file: ~/.claude.json (this project)

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`.

Config file: ~/.claude.json (this project)

With pipx installed:

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

Config file: ~/.claude.json (this project)

With pipx installed:

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

Config file: ~/.claude.json (all projects)

With pipx installed:

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

Config file: ~/.claude.json (all projects)

With pipx installed:

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

Config file: ~/.claude.json (all projects)

With pipx installed:

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

Config file: .mcp.json (in repo, version-controlled)

With pipx installed:

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

Config file: .mcp.json (in repo, version-controlled)

With pipx installed:

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

Config file: .mcp.json (in repo, version-controlled)

Install the packages first:

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

Then register:

$ claude mcp add tmux -- libtmux-mcp

Config file: ~/.claude.json (this project)

Install the packages first:

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

Then register:

$ claude mcp add tmux -- libtmux-mcp

Config file: ~/.claude.json (this project)

Install the packages first:

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

Then register:

$ claude mcp add tmux -- libtmux-mcp

Config file: ~/.claude.json (this project)

Install the packages first:

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

Then register:

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

Config file: ~/.claude.json (all projects)

Install the packages first:

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

Then register:

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

Config file: ~/.claude.json (all projects)

Install the packages first:

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

Then register:

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

Config file: ~/.claude.json (all projects)

Install the packages first:

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

Then register:

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

Config file: .mcp.json (in repo, version-controlled)

Install the packages first:

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

Then register:

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

Config file: .mcp.json (in repo, version-controlled)

Install the packages first:

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

Then register:

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

Config file: .mcp.json (in repo, version-controlled)

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

Config file: ~/.codex/config.toml

With uvx installed:

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

Config file: ~/.codex/config.toml

With uvx installed:

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

Config file: ~/.codex/config.toml

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"]

Config file: .codex/config.toml (in repo)

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"]

Config file: .codex/config.toml (in repo)

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" }

Config file: .codex/config.toml (in repo)

With pipx installed:

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

Config file: ~/.codex/config.toml

With pipx installed:

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

Config file: ~/.codex/config.toml

With pipx installed:

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

Config file: ~/.codex/config.toml

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"]

Config file: .codex/config.toml (in repo)

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"]

Config file: .codex/config.toml (in repo)

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"]

Config file: .codex/config.toml (in repo)

Install the packages first:

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

Then register:

$ codex mcp add tmux -- libtmux-mcp

Config file: ~/.codex/config.toml

Install the packages first:

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

Then register:

$ codex mcp add tmux -- libtmux-mcp

Config file: ~/.codex/config.toml

Install the packages first:

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

Then register:

$ codex mcp add tmux -- libtmux-mcp

Config file: ~/.codex/config.toml

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"

Config file: .codex/config.toml (in repo)

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"

Config file: .codex/config.toml (in repo)

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"

Config file: .codex/config.toml (in repo)

With uvx installed:

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

Config file: ~/.gemini/settings.json

With uvx installed:

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

Config file: ~/.gemini/settings.json

With uvx installed:

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

Config file: ~/.gemini/settings.json

With uvx installed:

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

Config file: .gemini/settings.json (in repo)

With uvx installed:

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

Config file: .gemini/settings.json (in repo)

With uvx installed:

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

Config file: .gemini/settings.json (in repo)

With pipx installed:

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

Config file: ~/.gemini/settings.json

With pipx installed:

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

Config file: ~/.gemini/settings.json

With pipx installed:

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

Config file: ~/.gemini/settings.json

With pipx installed:

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

Config file: .gemini/settings.json (in repo)

With pipx installed:

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

Config file: .gemini/settings.json (in repo)

With pipx installed:

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

Config file: .gemini/settings.json (in repo)

Install the packages first:

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

Then register:

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

Config file: ~/.gemini/settings.json

Install the packages first:

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

Then register:

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

Config file: ~/.gemini/settings.json

Install the packages first:

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

Then register:

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

Config file: ~/.gemini/settings.json

Install the packages first:

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

Then register:

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

Config file: .gemini/settings.json (in repo)

Install the packages first:

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

Then register:

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

Config file: .gemini/settings.json (in repo)

Install the packages first:

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

Then register:

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

Config file: .gemini/settings.json (in repo)

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

If your client isn’t listed, any tool supporting MCP stdio transport will work with the JSON config pattern shown for Claude Desktop or Cursor. See Migration notes for the recommended tmux registration slug (existing libtmux registrations keep working).

MCP Inspector¶

For testing and debugging:

$ npx @modelcontextprotocol/inspector

Config file locations¶

Client	Config file	Format
Claude Code	`.mcp.json` (project) or `~/.claude.json` (local/user)	JSON
Claude Desktop	`claude_desktop_config.json`	JSON
Codex CLI	`~/.codex/config.toml` (user) or `.codex/config.toml` (project, manual)	TOML
Gemini CLI	`~/.gemini/settings.json` (user) or `.gemini/settings.json` (project)	JSON
Cursor	`.cursor/mcp.json` (project) or `~/.cursor/mcp.json` (global)	JSON

Local checkout (development)¶

For live development, point your client at a local checkout via uv --directory:

Claude Code:

$ claude mcp add \
    --scope user \
    tmux -- \
    uv --directory ~/work/python/libtmux-mcp \
    run libtmux-mcp

Codex CLI / Gemini CLI / Cursor

Codex CLI:

$ codex mcp add tmux -- \
    uv --directory ~/work/python/libtmux-mcp \
    run libtmux-mcp

Gemini CLI:

$ gemini mcp add \
    --scope user \
    tmux uv -- \
    --directory ~/work/python/libtmux-mcp \
    run libtmux-mcp

Cursor — add to ~/.cursor/mcp.json:

{
    "mcpServers": {
        "tmux": {
            "command": "uv",
            "args": [
                "--directory", "~/work/python/libtmux-mcp",
                "run", "libtmux-mcp"
            ]
        }
    }
}

Common pitfalls¶

Absolute paths: Some clients require absolute paths in config. Use $HOME/... or the full path instead of ~/....
Virtual environments: If using pip install, ensure the venv is activated or the libtmux-mcp binary is on your PATH.
Socket isolation: Set LIBTMUX_SOCKET in the env block to isolate the MCP server from your default tmux. See Configuration.