tmux MCP for Java

Install

Choose your client and configuration scope, then run the command or paste the configuration.

Build or install the server first:

$ ./gradlew :libtmux-mcp:installDist

Then register:

$ claude mcp add tmux -- /absolute/path/to/libtmux-mcp

Nothing publishes this server as a binary yet. The build writes a launcher at libtmux-mcp/build/install/libtmux-mcp/bin/libtmux-mcp; use its absolute path.

Config file: ~/.claude.json (this project)

Build or install the server first:

$ ./gradlew :libtmux-mcp:installDist

Then register:

$ claude mcp add tmux --scope user -- /absolute/path/to/libtmux-mcp

Nothing publishes this server as a binary yet. The build writes a launcher at libtmux-mcp/build/install/libtmux-mcp/bin/libtmux-mcp; use its absolute path.

Config file: ~/.claude.json (all projects)

Build or install the server first:

$ ./gradlew :libtmux-mcp:installDist

Then register:

$ claude mcp add tmux --scope project -- /absolute/path/to/libtmux-mcp

Nothing publishes this server as a binary yet. The build writes a launcher at libtmux-mcp/build/install/libtmux-mcp/bin/libtmux-mcp; use its absolute path.

Config file: .mcp.json (in repo, version-controlled)

Build or install the server first:

$ ./gradlew :libtmux-mcp:installDist

Then use this config:

{
    "mcpServers": {
        "tmux": {
            "command": "/absolute/path/to/libtmux-mcp"
        }
    }
}

Nothing publishes this server as a binary yet. The build writes a launcher at libtmux-mcp/build/install/libtmux-mcp/bin/libtmux-mcp; use its absolute path.

Config file: claude_desktop_config.json

Build or install the server first:

$ ./gradlew :libtmux-mcp:installDist

Then register:

$ codex mcp add tmux -- /absolute/path/to/libtmux-mcp

Nothing publishes this server as a binary yet. The build writes a launcher at libtmux-mcp/build/install/libtmux-mcp/bin/libtmux-mcp; use its absolute path.

Config file: ~/.codex/config.toml

Build or install the server first:

$ ./gradlew :libtmux-mcp:installDist

Then register:

Codex's CLI doesn't support project scope yet — paste this into .codex/config.toml at the repo root.

[mcp_servers.tmux]
command = "/absolute/path/to/libtmux-mcp"

Nothing publishes this server as a binary yet. The build writes a launcher at libtmux-mcp/build/install/libtmux-mcp/bin/libtmux-mcp; use its absolute path.

Config file: .codex/config.toml (in repo)

Build or install the server first:

$ ./gradlew :libtmux-mcp:installDist

Then register:

$ gemini mcp add --scope user tmux /absolute/path/to/libtmux-mcp

Nothing publishes this server as a binary yet. The build writes a launcher at libtmux-mcp/build/install/libtmux-mcp/bin/libtmux-mcp; use its absolute path.

Config file: ~/.gemini/settings.json

Build or install the server first:

$ ./gradlew :libtmux-mcp:installDist

Then register:

$ gemini mcp add --scope project tmux /absolute/path/to/libtmux-mcp

Nothing publishes this server as a binary yet. The build writes a launcher at libtmux-mcp/build/install/libtmux-mcp/bin/libtmux-mcp; use its absolute path.

Config file: .gemini/settings.json (in repo)

Build or install the server first:

$ ./gradlew :libtmux-mcp:installDist

Then use this config:

{
    "mcpServers": {
        "tmux": {
            "command": "/absolute/path/to/libtmux-mcp"
        }
    }
}

Nothing publishes this server as a binary yet. The build writes a launcher at libtmux-mcp/build/install/libtmux-mcp/bin/libtmux-mcp; use its absolute path.

Config file: .cursor/mcp.json (in repo)

Build or install the server first:

$ ./gradlew :libtmux-mcp:installDist

Then use this config:

{
    "mcpServers": {
        "tmux": {
            "command": "/absolute/path/to/libtmux-mcp"
        }
    }
}

Nothing publishes this server as a binary yet. The build writes a launcher at libtmux-mcp/build/install/libtmux-mcp/bin/libtmux-mcp; use its absolute path.

Config file: ~/.cursor/mcp.json

Build or install the server first:

$ ./gradlew :libtmux-mcp:installDist

Then register:

$ grok mcp add --scope user tmux -- /absolute/path/to/libtmux-mcp

Nothing publishes this server as a binary yet. The build writes a launcher at libtmux-mcp/build/install/libtmux-mcp/bin/libtmux-mcp; use its absolute path.

Config file: ~/.grok/config.toml

Build or install the server first:

$ ./gradlew :libtmux-mcp:installDist

Then register:

$ grok mcp add --scope project tmux -- /absolute/path/to/libtmux-mcp

Nothing publishes this server as a binary yet. The build writes a launcher at libtmux-mcp/build/install/libtmux-mcp/bin/libtmux-mcp; use its absolute path.

Config file: ./.grok/config.toml (in repo)

Build or install the server first:

$ ./gradlew :libtmux-mcp:installDist

Then use this config:

{
    "mcpServers": {
        "tmux": {
            "command": "/absolute/path/to/libtmux-mcp"
        }
    }
}

Nothing publishes this server as a binary yet. The build writes a launcher at libtmux-mcp/build/install/libtmux-mcp/bin/libtmux-mcp; use its absolute path.

Config file: ~/.gemini/config/mcp_config.json

Build or install the server first:

$ ./gradlew :libtmux-mcp:installDist

Then register:

$ opencode mcp add tmux -- /absolute/path/to/libtmux-mcp

Nothing publishes this server as a binary yet. The build writes a launcher at libtmux-mcp/build/install/libtmux-mcp/bin/libtmux-mcp; use its absolute path.

Config file: ~/.config/opencode/opencode.jsonc

io.github.libtmux:libtmux-mcp provides a Java MCP server and a libtmux-mcp application launcher. It discovers tmux objects, captures terminal output, runs framed shell commands, and applies typed topology operations.

Use JDK 21 or newer and tmux. The launcher selects its endpoint and toolsets at startup. It serves MCP over stdin and stdout.

Start here¶

Install points an MCP client at this server.
Tools lists the MCP operations, arguments, and results.
Guides build the launcher and connect a client.
Topics explain toolsets, input preflight, and wait semantics.
Examples call a tool, then explore server internals.
Language API documents embedding and implementation types.

The only MCP resource is the static tmux://capabilities report. The server does not register workflow prompts or dynamic resource subscriptions.

The Workspace Manager is a separate Java module. Application code can parse and build declarative workspaces; MCP clients compose the exposed topology tools.

Module documentation.

Scripting & web

Compiled & native

JVM

.NET

tmux

tmux MCP for Java

Install

Start here¶