libtmux-mcp

A Model Context Protocol server for tmux, built on libtmux.

Warning

Pre-alpha. APIs may change. Contributions and feedback welcome.

Give your AI agent hands inside the terminal — create sessions, run commands, read output, orchestrate panes.

Tools

Module	Tools
Server	list_sessions, create_session, kill_server, get_server_info
Session	list_windows, create_window, rename_session, kill_session
Window	list_panes, split_window, rename_window, kill_window, select_layout, resize_window
Pane	send_keys, capture_pane, resize_pane, kill_pane, set_pane_title, get_pane_info, clear_pane, search_panes, wait_for_text
Options	show_option, set_option
Environment	show_environment, set_environment

Quickstart

Requirements: Python 3.10+, tmux on $PATH.

Install and run:

uvx libtmux-mcp

Claude Code

claude mcp add tmux -- uvx libtmux-mcp

Codex CLI

codex mcp add tmux -- uvx libtmux-mcp

Gemini CLI

gemini mcp add tmux uvx -- libtmux-mcp

Claude Desktop

Add to claude_desktop_config.json:

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

More clients and JSON config: client setup docs

What it feels like

You: Create a session called "api" and run pytest tests/api/ -x in it.

Agent: Created session api with window tests. Running pytest now. Here's the output — 14 passed, 2 failed. The failures are in test_auth.py::test_token_refresh and test_auth.py::test_expired_session. Want me to open those files?

The agent manages tmux directly. No copy-pasting terminal output. No switching windows to check on long-running processes.

Documentation

Full docs, guides, and tool reference: libtmux-mcp.git-pull.com

Development

Clone and install:

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

cd libtmux-mcp

uv sync --dev

Run the server locally:

uv run libtmux-mcp

Run tests:

uv run pytest

Related projects

• libtmux — Python API for tmux
• tmuxp — tmux session manager
• The Tao of tmux — the book

License

MIT