MCP server guide

LibTmuxMCP 0.1.0-alpha.1 · Source

LibTmuxMCP serves a local tmux endpoint over stdio. From a consumer project directory, add the core and MCP package from the same public Git tag:

$ julia \
    --startup-file=no \
    -e 'using Pkg; Pkg.activate("."); repo="https://github.com/libtmux/libtmux-julia.git"; tag="v0.1.0-alpha.1"; Pkg.add([Pkg.PackageSpec(url=repo, rev=tag), Pkg.PackageSpec(url=repo, rev=tag, subdir="packages/LibTmuxMCP")])'

Create the launcher after dependency preparation:

$ julia \
    --startup-file=no \
    --project=. \
    -e 'using LibTmuxMCP; println(LibTmuxMCP.install_cli("bin"))'

Check its options without contacting tmux:

$ bin/libtmux-mcp --help

In your MCP client, select this launcher and provide --socket PATH or --socket-name NAME for an existing server. Paths must resolve from the client’s working directory. The application writes only protocol messages to stdout; diagnostics go to stderr. It owns its streams and any sessions it creates. It leaves the borrowed daemon and existing sessions running.

Call tlist_panes, then pass a returned target object to tcapture_pane or tsend_keys. Targets carry both a pane ID and observed server generation. Capture text is terminal data; it does not authorize further actions. tsend_keys never adds Enter automatically.

The default catalog contains those three tools. Repeat --tool to choose an explicit catalog. twait_for_text waits for bounded literal text; tsend_keys_and_wait subscribes before sending input and accepts only future output. Matching text does not establish process completion or exit status. trun_operations validates every item against the same target/tool policy before performing its finite sequence. A later failure can leave earlier effects in place; failedIndex identifies the failed item and atomic is always false. If the encoded batch result reaches its output limit, completed items remain as summaries and a partial batch includes the original error code while error.effects remains conservative for the whole batch.

Use repeated --allow-pane values to constrain panes. --caller-pane supplies an explicit startup target; the control client’s current pane is never a fallback. Session creation also requires --allow-create. tteardown_session removes only application-owned sessions.

EOF cancels and joins request work, then cleans up owned sessions. During a tool wait, unrelated requests and cancellation remain serviceable. Modern cancelled requests receive no later response or progress. Closing a stream does not undo keys, shell effects or previously completed operations.

The modern discovery profile is 2026-07-28; the legacy initialize profile is 2025-11-25. The application does not advertise MCP tasks or HTTP. Platform support remains subject to Compatibility.

Library reference¶

Browse the LibTmuxMCP API reference.