Troubleshooting

Symptom-based guide. Find your problem, follow the steps.

Server doesn’t appear in client

Symptoms: Client shows no tmux MCP tools, or “server not found” errors.

Check:

  1. Verify the server starts manually:

    $ uvx libtmux-mcp

    You should see no output (it’s waiting for stdio input). Press Ctrl+C to stop.

  2. Check your client config points to the right command. Common issues:

    • uvx not in PATH — install uv

    • Typo in "command" or "args" in JSON config

    • TOML config syntax errors (Codex CLI)

  3. Restart your MCP client after config changes.

Tools fail with “no sessions found”

Symptoms: list_sessions returns empty, other tools can’t find targets.

Check:

  1. Is tmux running?

    $ tmux list-sessions

  2. Are you on the right socket? If LIBTMUX_SOCKET is set, the server only sees sessions on that socket:

    $ tmux -L ai_workspace list-sessions

  3. Create a session on the expected socket:

    $ tmux -L ai_workspace new-session -d -s test

Wrong tmux socket

Symptoms: Server sees different sessions than expected, or sees nothing.

Cause: LIBTMUX_SOCKET in the MCP config selects a different tmux socket. Your personal sessions are on the default socket.

Fix: Either remove LIBTMUX_SOCKET from the config to use the default socket, or ensure sessions exist on the configured socket.

Pane targeting mismatch

Symptoms: Tool targets the wrong pane, or “pane not found” errors.

Cause: Using ambiguous targeting (session name + window name) instead of direct IDs.

Fix: Use pane_id (e.g. %1) for unambiguous targeting. Pane IDs are globally unique within a tmux server. Run list_panes first to discover IDs.

Command works in shell but not via MCP

Symptoms: send_keys sends the command but output isn’t what you expect.

Check:

  1. Enter key: send_keys sends Enter by default (enter=true). If you’re sending a partial command, set enter=false.

  2. Special characters: tmux interprets some key names (e.g. C-c, Enter). If sending literal text, use literal=true.

  3. Timing: For authored shell commands, prefer run_command; it waits for completion and returns exit status plus output. Use send_keys or send_keys_batch for raw interactive input, capture_since for repeated observation, and wait_for_text only when waiting on output you do not author. Don’t call capture_pane immediately after raw input — the command may still be running.

Silent startup failure

Symptoms: MCP client says connected but no tools are available.

Check:

  1. Missing dependency — ensure FastMCP is installed:

    $ uvx libtmux-mcp

    If using pip install, check:

    $ python -c "import fastmcp; print(fastmcp.__version__)"

  2. Python version — requires 3.10+:

    $ python --version

A toolset is hiding tools

Symptoms: Some tools are missing from the tool list, or a call returns “not in this server’s enabled toolsets”.

Cause: LIBTMUX_TOOLSETS does not include the tool’s toolset.

Fix: The default is inspect,manage,execute. Add teardown for the kill commands, or name the tool in LIBTMUX_TOOLS. See Trust model.

How to see logs

The MCP server uses Python’s standard logging module. To see debug output, set the log level before starting:

$ PYTHONUNBUFFERED=1 uvx libtmux-mcp 2>server.log

For Claude Desktop on macOS, MCP server logs are at: ~/Library/Logs/Claude/mcp-server-libtmux.log