
tmux-mcp
io.github.fr1sk由 GitHub 帳號 fr1sk 發布v0.3.3更新於 Oct 24, 2026
MCP server for tmux — browse sessions, capture output, send commands.
概覽
本機 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 金鑰。
安裝
在 SourceWeft 中
- 開啟 儀表板中的 tmux-mcp,將其新增到工作區。
- 為需要使用其工具的對話啟用該服務。
Desktop only,透過 STDIO。 STDIO 服務會啟動本機處理程序,因此需要 SourceWeft 桌面主機。
其他 MCP 客戶端
參照 儲存庫 中的啟動說明。
README
tmux-mcp
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-cto interrupt,Escapeto 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.
Returns: window index, name, pane count, whether it's the active window.
list_panes
Lists panes inside a session or window.
Returns: pane index, title, dimensions (e.g. 220x50), whether it's active, running command.
capture_pane
Captures the current terminal output of a pane.
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.
Returns: confirmation + pane output after the command ran.
new_session
Creates a new detached tmux session.
new_window
Creates a new window inside an existing session.
split_pane
Splits a pane into two.
kill_session
Kills a session and all its windows and panes. Destructive — cannot be undone.
kill_window
Kills a window and all its panes. Destructive.
kill_pane
Kills a single pane and its running process. Destructive.
rename_session
rename_window
Target format
All tools use tmux's standard session:window.pane notation:
Use list_sessions → list_windows → list_panes to discover the right target before calling capture_pane or send_keys.
Install
Configure
OpenCode (~/.config/opencode/opencode.json)
Claude Code (~/.claude/settings.json)
Cursor / Windsurf (mcp.json)
Usage examples
Environment variables
Set these in your MCP client config under environment to control agent behavior.
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):
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.commandparameter onnew_session,new_window, andsplit_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版本歷史
1- v0.3.3最新Sep 16, 2026
評分
已滿足適用檢查項的 50%
該評分衡量此收錄條目的完整程度,依據註冊中心條目、端點與公開來源計算得出。它不是對伺服器本身的評價,也不表示伺服器安全或目前可用:可連通性是帶日期的檢查結果,評分也不包含安裝量或使用者評價。
- 近 30 天內可連通25 分
請保持端點能夠回應 MCP 握手;SourceWeft 每 30 天探測一次。
- 已宣告認證方式10 分
請在註冊中心條目中宣告憑證請求標頭,或保持端點能夠回應探測,以便判定其認證方式。
- 已列出工具15 分
請讓伺服器在無憑證時回應 tools/list,或發布可在沙箱中無憑證啟動的軟體包。
- 描述必需15 分
- 圖示10 分
- 文件15 分
- 授權條款10 分