libtmux-mcp

MCP server for tmux, powered by libtmux.

Warning

Pre-alpha. APIs may change. Feedback welcome.

One-liner setup (no clone needed)

uvx handles install, deps, and execution automatically:

Claude Code:

$ claude mcp add libtmux -- uvx libtmux-mcp

Codex CLI:

$ codex mcp add libtmux -- uvx libtmux-mcp

Gemini CLI:

$ gemini mcp add libtmux uvx -- libtmux-mcp

Cursor does not have an mcp add CLI command - use the JSON config below.

JSON config (all tools)

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

Tool	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 (see below)
Gemini CLI	~/.gemini/settings.json	JSON
Cursor	.cursor/mcp.json (project) or ~/.cursor/mcp.json (global)	JSON

Codex CLI config.toml format

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

Install with pip / uv

$ uv pip install libtmux-mcp

$ pip install libtmux-mcp

Development install

Clone and install in editable mode:

$ git clone https://github.com/tmux-python/libtmux-mcp.git

$ cd libtmux-mcp

$ uv pip install -e "."

Run the server:

$ libtmux-mcp

Code changes take effect immediately - no reinstall needed.

Local checkout CLI setup

Point your tool at the local checkout via uv --directory:

Claude Code:

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

Codex CLI:

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

Gemini CLI:

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

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

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

Codex CLI config.toml format (local checkout)

[mcp_servers.libtmux]
command = "uv"
args = ["--directory", "~/work/python/libtmux-mcp", "run", "libtmux-mcp"]