libtmux-mcp server

官方

由 libtmux 驅動的 tmux MCP 伺服器

造訪 git-pull.com試用此 MCP贊助

你可以用 Libtmux MCP 做什麼？

  • 檢查 tmux 狀態 — 透過 list_sessions、capture_pane 或 get_pane_info 取得工作階段、視窗或窗格的唯讀快照。
  • 在窗格中執行命令 — 讓助理使用 run_command 或 send_keys 執行 shell 命令或傳送按鍵，包括批次操作。
  • 管理 tmux 物件 — 使用 create_window、split_window 或 select_pane 等工具建立、分割、調整大小或選取視窗與窗格。
  • 銷毀 tmux 資源 — 使用 kill_session 或 kill_server 等破壞性工具終止工作階段、視窗、窗格或整個伺服器。
  • 抑制 shell 歷史記錄 — 以 suppress_persistent_history=true 啟動工作階段或視窗，讓測試執行不會寫入持續性的 shell 歷史記錄。

文件

libtmux-mcp¶

Terminal control for AI agents, built on libtmux and FastMCP.

This server maps tmux's object hierarchy — sessions, windows, panes — into MCP tools. Some tools read state. Some mutate it. Some destroy. The distinction is explicit and enforced.

Warning

Pre-alpha. APIs may change. Feedback welcome.

Claude Code Claude Desktop Codex CLI Gemini CLI Cursor Grok CLI Antigravity opencode

uvx pipx pip install

Configure cooldowns ?

Local User Project

User Project

User Project

Project Global

User Project

With uvx installed:

$ claude mcp add tmux -- uvx libtmux-mcp

Back

Dependency cooldowns

Use the Configure cooldowns checkbox above to enable or disable. These settings choose how cooldown behaves once enabled.

What are cooldowns?

Cooldowns delay picking up newly uploaded packages so the community has time to spot supply-chain attacks before you install. Most package managers don't apply one by default — you opt in via a global setting in your tool's config.

Learn more at cooldowns.dev · Datadog Security Labs writeup.

Quickstart

Install, connect, get a first result. Under 2 minutes.

Quickstart

Tools

Every tool, grouped by intent and safety tier.

Tools

Prompts

Four workflow recipes the client renders for the model.

Prompts

Resources

Snapshot views of the tmux hierarchy via tmux:// URIs.

Resources

Safety tiers

Readonly, mutating, destructive. Know what changes state.

Safety tiers

Client setup

Config blocks for Claude Desktop, Claude Code, Cursor, and others.

MCP Clients

What you can do¶

Inspect readonly¶

Read tmux state without changing anything.

list_sessions · capture_pane · capture_since · snapshot_pane · get_pane_info · find_pane_by_position · search_panes · wait_for_text · display_message · call_readonly_tools_batch

Act mutating¶

Create or modify tmux objects.

create_session · send_keys · send_keys_batch · run_command · paste_text · create_window · split_window · select_pane · select_window · move_window · resize_pane · pipe_pane · set_option · call_mutating_tools_batch

Destroy destructive¶

Tear down tmux objects. Not reversible.

kill_session · kill_window · kill_pane · kill_server · call_destructive_tools_batch

Example: keep test runs out of persistent history¶

libtmux-mcp provides best-effort history suppression for Bash, Zsh, and Fish. MCP calls to run_command use lightweight command suppression by default. When you create a new shell, opt into stronger no-disk controls withsuppress_persistent_history=true.

Prompt

Create a tmux session called "checks" with best-effort no-disk shell-history controls, run pytest -q in its initial pane, and show me the result.

The agent calls create_session withsuppress_persistent_history=true, reuses active_pane_id from the returnedSessionInfo, and callsrun_command without an override. The same spawn option oncreate_window, split_window, orrespawn_pane applies only to the process that call starts.

These controls reduce history noise; they do not make commands secret. SeeHistory suppression for shell-specific behavior,Configuration for the server default, and Safety tiers for other observation surfaces.

Browse all tools →

Mental model¶

  • Object hierarchy — sessions contain windows, windows contain panes (Concepts)
  • Read vs. mutate — some tools observe, some act, some destroy (Safety tiers)
  • tmux is the source of truth — the server reads from it and writes to it, never caches or abstracts