MCP Clients¶

Copy-pasteable configuration for every supported MCP client. If your client isn’t listed, any tool supporting MCP stdio transport will work with the JSON config pattern.

See Migration notes for the recommended tmux registration slug (existing libtmux registrations keep working).

Claude Code¶

uvx

With uv installed:

$ claude mcp add tmux -- uvx libtmux-mcp

pipx

With pipx installed:

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

pip install

Install the packages first:

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

Then register:

$ claude mcp add tmux -- libtmux-mcp

Config file: .mcp.json (project) or ~/.claude.json (global).

Claude Desktop¶

Add to claude_desktop_config.json:

uvx

With uv installed:

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

pipx

With pipx installed:

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

pip install

Install the packages first:

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

Then use this config:

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

Codex CLI¶

uvx

With uv installed:

$ codex mcp add tmux -- uvx libtmux-mcp

pipx

With pipx installed:

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

pip install

Install the packages first:

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

Then register:

$ codex mcp add tmux -- libtmux-mcp

config.toml format

Add to ~/.codex/config.toml:

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

Gemini CLI¶

uvx

With uv installed:

$ gemini mcp add tmux uvx -- libtmux-mcp

pipx

With pipx installed:

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

pip install

Install the packages first:

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

Then register:

$ gemini mcp add tmux libtmux-mcp

Config file: ~/.gemini/settings.json (JSON format, same schema as Claude Desktop).

Cursor¶

Add to .cursor/mcp.json (project) or ~/.cursor/mcp.json (global):

uvx

With uv installed:

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

pipx

With pipx installed:

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

pip install

Install the packages first:

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

Then use this config:

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

MCP Inspector¶

For testing and debugging:

$ npx @modelcontextprotocol/inspector

Config file locations¶

Client	Config file	Format
Claude Code	`.mcp.json` (project) or `~/.claude.json` (global)	JSON
Claude Desktop	`claude_desktop_config.json`	JSON
Codex CLI	`~/.codex/config.toml`	TOML
Gemini CLI	`~/.gemini/settings.json`	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.