Tmux MCP Server

Model Context Protocol server that enables Claude Desktop to interact with and view tmux session content. This integration allows AI assistants to read from, control, and observe your terminal sessions.

Features

• List and search tmux sessions
• View and navigate tmux windows and panes
• Capture and expose terminal content from any pane
• Execute commands in tmux panes and retrieve results (use it at your own risk ⚠️)
• Create new tmux sessions and windows
• Split panes horizontally or vertically with customizable sizes
• Kill tmux sessions, windows, and panes

Check out this short video to get excited!

Prerequisites

• Node.js
• tmux installed and running

Usage

Configure Claude Desktop

Add this MCP server to your Claude Desktop configuration:

"mcpServers": {
  "tmux": {
    "command": "npx",
    "args": ["-y", "tmux-mcp"]
  }
}

MCP server options

You can optionally specify the command line shell you are using, if unspecified it defaults to bash

"mcpServers": {
  "tmux": {
    "command": "npx",
    "args": ["-y", "tmux-mcp", "--shell-type=fish"]
  }
}

The MCP server needs to know the shell only when executing commands, to properly read its exit status.

Available Resources

• tmux://sessions - List all tmux sessions
• tmux://pane/{paneId} - View content of a specific tmux pane
• tmux://command/{commandId}/result - Results from executed commands

Available Tools

• list-sessions - List all active tmux sessions
• find-session - Find a tmux session by name
• list-windows - List windows in a tmux session
• list-panes - List panes in a tmux window
• capture-pane - Capture content from a tmux pane
• create-session - Create a new tmux session
• create-window - Create a new window in a tmux session
• split-pane - Split a tmux pane horizontally or vertically with optional size
• kill-session - Kill a tmux session by ID
• kill-window - Kill a tmux window by ID
• kill-pane - Kill a tmux pane by ID
• execute-command - Execute a command in a tmux pane
• get-command-result - Get the result of an executed command
• role-list - List known roles and role→session mapping
• role-add - Add/update role definition (name + md/mdPath + optional model flags)
• role-get - Get role definition
• role-remove - Remove role definition
• role-enable - Enable a role
• role-disable - Disable a role
• role-start - Start/reuse a registered role session and launch Codex workflow
• role-send - Send keys/text to a role pane
• role-capture - Capture output from a role pane
• role-wait - Wait for text/pattern in a role pane
• role-stop - Stop a role session
• init-get - Get INIT rules
• init-set - Set INIT rules
• session-list - List persisted sessions registry
• session-add - Add a session entry to registry
• session-update - Update a session entry
• session-remove - Remove a session entry
• session-clear - Clear all registry entries

Role defs file: roles.json (override TMUX_MCP_ROLES_PATH). INIT rules file: INIT.md (override TMUX_MCP_INIT_PATH). Role markdown directory: roles/ next to roles.json (override TMUX_MCP_ROLE_MD_DIR).

Role-based orchestration (optional)

Roles default to: planner, planner_ai, coder, reviewer, qa. Role sessions default to role-<role>. Registry path: sessions.json (override with TMUX_MCP_REGISTRY_PATH). Note: role-start only accepts registered roles from roles.json (no implicit role creation). Note: If role-start is called without command, it runs Codex with a prompt that enforces this order: INIT.md -> <role>.md -> task. Note: role-start is Codex-focused; non-Codex commands are rejected. Model defaults and overrides:

• Built-in defaults include planner -> --model gpt-5.3-codex-spark --skip-git-repo-check.
• coder, reviewer, qa default to --skip-git-repo-check.
• You can set per-role defaults via role-add (model, skipGitRepoCheck, mdPath).
• You can override per-run via role-start (model, skipGitRepoCheck, task).
• --skip-git-repo-check is applied only if the local Codex CLI supports that flag.

Examples:

• role-start role=planner task="analiz et" -> runs Codex with planner defaults.
• role-start role=planner model="gpt-5.3-codex-spark" skipGitRepoCheck=true task="analiz et" -> per-run override.
• role-add name=planner mdPath="/opt/roles/planner.md" model="gpt-5.3-codex-spark" skipGitRepoCheck=true -> persist per-role defaults.