tmux-mcp

io.github.fr1sk由 GitHub 帳號 fr1sk 發布v0.3.3更新於 Oct 24, 2026

MCP server for tmux — browse sessions, capture output, send commands.

概覽

AI 產生的概覽

本機 MCP 伺服器,讓 AI 助理瀏覽 tmux 工作階段、視窗與窗格,讀取終端機輸出,並送出指令或按鍵序列。

可以做什麼
列出工作階段、視窗與窗格及其狀態、尺寸與執行中的指令,並可重新命名以便準確定位。擷取任一窗格的可見輸出與回捲內容,最多 5000 行。對窗格送出 shell 指令或 Ctrl-C、Escape 等原始按鍵,並在可設定的等待後讀取結果。建立工作階段、視窗與分割窗格,可指定工作目錄與初始指令。終止工作階段、視窗或個別窗格。
適用情境
適合在 tmux 中工作時使用:讓助理查看執行中的開發伺服器、日誌、測試執行或編譯錯誤,並在可見、可稽核的終端機工作階段中執行指令,而不是在看不見的 shell 中。
執行需求
以本機程序從 npm 安裝執行,需要 Node.js 18 或更新版本,且 tmux 位於 PATH 中。選用環境變數 TMUX_MCP_ALWAYS_USE 與 TMUX_MCP_DEFAULT_SESSION 可控制是否將指令導向指定工作階段。不需要帳號或 API 金鑰。
安裝前請注意
提供不受限制的本機 shell 存取:send_keys 以及 new_session、new_window、split_pane 的 command 參數會以你的權限執行任意指令,且沒有沙箱。capture_pane 傳回原始終端機文字,可能包含 API 金鑰、權杖、密碼或 SSH 私鑰。終止類工具具破壞性且無法復原。僅在可信任的本機環境使用,切勿暴露給不可信任的助理或可經網路存取的主機。

安裝

在 SourceWeft 中

  1. 開啟 儀表板中的 tmux-mcp,將其新增到工作區。
  2. 為需要使用其工具的對話啟用該服務。

Desktop only,透過 STDIO。 STDIO 服務會啟動本機處理程序,因此需要 SourceWeft 桌面主機。

其他 MCP 客戶端

參照 儲存庫 中的啟動說明。

README

tmux-mcp

[tmux-mcp logo]

MCP server that gives AI assistants full visibility into your tmux sessions — browse sessions, windows, and panes, read terminal output, and send commands.

Watch your AI agent work in real-time. Enable TMUX_MCP_ALWAYS_USE to force every shell command through a named tmux session instead of direct Bash — every command your AI runs appears live in your terminal, fully auditable.

Works with Claude Code, OpenCode, Cursor, Windsurf, and any MCP-compatible host.

What it can do

Read your terminal state

  • List every active tmux session with window count, creation time, and attached status
  • List windows inside a session — index, name, pane count, which one is active
  • List panes inside a window — size, running command, which one is active

See what's on screen

  • Capture the visible output of any pane — up to 5 000 lines of scrollback
  • Read logs, compiler errors, server output, test runs — anything in your terminal

Create and organise

  • Create sessions, windows, and panes with a working directory and an initial command
  • Split panes horizontally or vertically
  • Rename sessions and windows for reliable targeting

Clean up

  • Kill sessions, windows, or individual panes

Control panes

  • Send shell commands to any pane and immediately read the output
  • Send raw key sequences: C-c to interrupt, Escape to exit, arrow keys, etc.
  • Configurable wait time before capturing so long-running commands have time to finish

Error-safe

  • Bad target? No tmux server? Returns a readable error message instead of crashing

Tools

list_sessions

Lists all active tmux sessions. No parameters.

Returns: session name, number of windows, creation time, attached/detached status.

list_windows

Lists windows inside a session.

ParameterTypeDescription
sessionstringSession name (from list_sessions)

Returns: window index, name, pane count, whether it's the active window.

list_panes

Lists panes inside a session or window.

ParameterTypeDescription
targetstringSession name (work) or session:window (work:0)

Returns: pane index, title, dimensions (e.g. 220x50), whether it's active, running command.

capture_pane

Captures the current terminal output of a pane.

ParameterTypeDefaultDescription
targetstring—Pane target: session:window.pane (e.g. work:0.0)
linesnumber150Lines of scrollback to include (max 5000)

Returns: raw terminal text as it appears on screen.

Security note: pane output can contain environment variables, API keys, tokens, and credentials if they were printed to the terminal. Only use this server in trusted local environments.

send_keys

Sends a command or key sequence to a pane and captures the result.

ParameterTypeDefaultDescription
targetstring—Pane target: session:window.pane
keysstring—Command or tmux key notation (C-c, Escape, Up, etc.)
enterbooleantruePress Enter after the keys
capture_linesnumber50Lines to capture after sending
wait_msnumber400Milliseconds to wait before capturing

Returns: confirmation + pane output after the command ran.

new_session

Creates a new detached tmux session.

ParameterTypeDescription
namestringSession name. Omit to let tmux auto-assign one.
cwdstringWorking directory for the session.
commandstringShell command to run immediately in the first window.

new_window

Creates a new window inside an existing session.

ParameterTypeDescription
sessionstringSession to create the window in.
namestringWindow name.
cwdstringWorking directory for the new window.
commandstringShell command to run immediately.

split_pane

Splits a pane into two.

ParameterTypeDefaultDescription
targetstring—Pane or window to split: session:window.pane
directionhorizontal | verticalhorizontalhorizontal = left/right split, vertical = top/bottom
cwdstring—Working directory for the new pane.
commandstring—Shell command to run in the new pane.
sizenumber—Size of the new pane as a percentage (1–99).

kill_session

Kills a session and all its windows and panes. Destructive — cannot be undone.

ParameterTypeDescription
sessionstringSession name to kill.

kill_window

Kills a window and all its panes. Destructive.

ParameterTypeDescription
targetstringWindow target: session:window

kill_pane

Kills a single pane and its running process. Destructive.

ParameterTypeDescription
targetstringPane target: session:window.pane

rename_session

ParameterTypeDescription
sessionstringCurrent session name.
new_namestringNew name.

rename_window

ParameterTypeDescription
targetstringWindow target: session:window
new_namestringNew name.

Target format

All tools use tmux's standard session:window.pane notation:

work           →  session named "work"work:0         →  window 0 of session "work"work:0.0       →  pane 0, window 0, session "work"work:editor.1  →  pane 1 of window named "editor" in session "work"

Use list_sessions → list_windows → list_panes to discover the right target before calling capture_pane or send_keys.

Install

bash
npm install -g @fr1sk/tmux-mcp

Configure

OpenCode (~/.config/opencode/opencode.json)

json
{  "mcp": {    "tmux": {      "type": "local",      "command": ["tmux-mcp"]    }  }}

Claude Code (~/.claude/settings.json)

json
{  "mcpServers": {    "tmux": {      "command": "tmux-mcp"    }  }}

Cursor / Windsurf (mcp.json)

json
{  "mcpServers": {    "tmux": {      "command": "tmux-mcp"    }  }}

Usage examples

What tmux sessions do I have running?
Show me the output of my dev server — it's in the work session
My tests are failing, check what's in work:1.0
Run git status in my work session and show me the output
Send Ctrl-C to work:0.0, the process is stuck
Tail the last 300 lines from the logs pane in my api session
Create a new session called 'dev' in ~/Projects/myapp and run npm run dev
Split work:0.0 vertically and run npm test in the new pane
Rename session 'new' to 'api'
Kill the old session named 'temp'

Environment variables

Set these in your MCP client config under environment to control agent behavior.

VariableDefaultDescription
TMUX_MCP_DEFAULT_SESSION—Session name the agent routes commands to when alwaysUseTmux is on
TMUX_MCP_ALWAYS_USEfalseSet to "true" to route all shell commands through tmux instead of direct Bash

When both are set, the get_config tool returns an instructions field the agent uses to automatically route every shell command through send_keys in the configured session.

Example (OpenCode):

json
{  "mcp": {    "tmux": {      "type": "local",      "command": ["tmux-mcp"],      "environment": {        "TMUX_MCP_ALWAYS_USE": "true",        "TMUX_MCP_DEFAULT_SESSION": "dev"      }    }  }}

Security

This server provides unrestricted local shell access through tmux:

  • capture_pane — returns raw terminal output, which may include environment variables, API keys, tokens, database passwords, and SSH private keys if they were printed to the terminal.
  • send_keys — executes arbitrary shell commands in the target pane. Any command the AI sends runs in your shell with your permissions.
  • command parameter on new_session, new_window, and split_pane — passed directly to tmux, which runs it via $SHELL -c. No validation or sandboxing.

Only use this server in trusted local development environments. Never expose it to network-accessible MCP hosts or untrusted AI assistants.

Requirements

  • Node.js 18+
  • tmux on $PATH

來源:README.md,提交 22389f3

工具

0
SourceWeft 尚未在沙箱中啟動過該軟體包,因此其工具未知。

版本歷史

1
  1. v0.3.3最新Sep 16, 2026

評分

已滿足適用檢查項的 50%

該評分衡量此收錄條目的完整程度,依據註冊中心條目、端點與公開來源計算得出。它不是對伺服器本身的評價,也不表示伺服器安全或目前可用:可連通性是帶日期的檢查結果,評分也不包含安裝量或使用者評價。

  • 近 30 天內可連通25 分

    請保持端點能夠回應 MCP 握手;SourceWeft 每 30 天探測一次。

  • 已宣告認證方式10 分

    請在註冊中心條目中宣告憑證請求標頭,或保持端點能夠回應探測,以便判定其認證方式。

  • 已列出工具15 分

    請讓伺服器在無憑證時回應 tools/list,或發布可在沙箱中無憑證啟動的軟體包。

  • 描述必需15 分
  • 圖示10 分
  • 文件15 分
  • 授權條款10 分