tmux-mcp

tmux-mcp

为 AI 助手提供全面查看 tmux 会话的 MCP 服务——浏览会话、窗口和窗格，读取终端输出并发送命令。

实时查看 AI Agent 的工作过程。 启用 TMUX_MCP_ALWAYS_USE，即可强制所有 shell 命令通过指定的 tmux 会话运行，而不是直接通过 Bash 运行——AI 执行的每条命令都会实时显示在终端中，并且全程可审计。

适用于 Claude Code、OpenCode、Cursor、Windsurf，以及任何兼容 MCP 的主机。

功能

读取终端状态

• 列出所有活动的 tmux 会话，包括窗口数、创建时间和连接状态
• 列出会话中的窗口，包括索引、名称、窗格数和当前活动窗口
• 列出窗口中的窗格，包括大小、正在运行的命令和当前活动窗格

查看屏幕内容

• 捕获任意窗格的可见输出——最多可读取 5 000 行回滚内容
• 读取日志、编译器错误、服务输出、测试运行结果——终端中的任何内容

创建和整理

• 创建会话、窗口和窗格，并设置工作目录和初始命令
• 水平或垂直拆分窗格
• 重命名会话和窗口，以便可靠定位

清理

• 终止会话、窗口或单个窗格

控制窗格

• 向任意窗格发送 shell 命令并立即读取输出
• 发送原始按键序列：使用 C-c 中断、使用 Escape 退出、发送方向键等
• 可配置捕获输出前的等待时间，确保长时间运行的命令有足够时间完成

安全处理错误

• 目标无效？没有 tmux 服务？不会崩溃，而是返回易读的错误消息

工具

list_sessions

列出所有活动的 tmux 会话。无需参数。

返回：会话名称、窗口数、创建时间、已连接或已断开状态。

list_windows

列出会话中的窗口。

参数	类型	说明
session	string	会话名称（来自 list_sessions）

返回：窗口索引、名称、窗格数，以及是否为当前活动窗口。

list_panes

列出会话或窗口中的窗格。

参数	类型	说明
target	string	会话名称（work）或 session:window（work:0）

返回：窗格索引、标题、尺寸（例如 220x50）、是否为活动窗格、正在运行的命令。

capture_pane

捕获窗格当前的终端输出。

参数	类型	默认值	说明
target	string	—	窗格目标：session:window.pane（例如 work:0.0）
lines	number	150	要包含的回滚行数（最多 5000 行）

返回：屏幕上显示的原始终端文本。

安全提示： 如果环境变量、API 密钥、令牌和凭据曾输出到终端，窗格输出可能包含这些内容。请仅在可信的本地环境中使用此服务。

send_keys

向窗格发送命令或按键序列，并捕获执行结果。

参数	类型	默认值	说明
target	string	—	窗格目标：session:window.pane
keys	string	—	命令或 tmux 按键表示法（C-c、Escape、Up 等）
enter	boolean	true	发送按键后是否按 Enter
capture_lines	number	50	发送按键后要捕获的行数
wait_ms	number	400	捕获前的等待毫秒数

返回：确认信息 + 命令运行后的窗格输出。

new_session

创建一个新的分离式 tmux 会话。

参数	类型	说明
name	string	会话名称。不填写时由 tmux 自动分配。
cwd	string	会话的工作目录。
command	string	在第一个窗口中立即运行的 shell 命令。

new_window

在现有会话中创建新窗口。

参数	类型	描述
session	string	要在其中创建窗口的会话。
name	string	窗口名称。
cwd	string	新窗口的工作目录。
command	string	立即运行的 Shell 命令。

split_pane

将窗格拆分为两个窗格。

参数	类型	默认值	描述
target	string	—	要拆分的窗格或窗口：session:window.pane
direction	horizontal | vertical	horizontal	horizontal = 左右拆分，vertical = 上下拆分
cwd	string	—	新窗格的工作目录。
command	string	—	要在新窗格中运行的 Shell 命令。
size	number	—	新窗格的大小，以百分比表示（1–99）。

kill_session

终止会话及其所有窗口和窗格。具有破坏性，无法撤销。

参数	类型	描述
session	string	要终止的会话名称。

kill_window

终止窗口及其所有窗格。具有破坏性。

参数	类型	描述
target	string	窗口目标：session:window

kill_pane

终止单个窗格及其运行中的进程。具有破坏性。

参数	类型	描述
target	string	窗格目标：session:window.pane

rename_session

参数	类型	描述
session	string	当前会话名称。
new_name	string	新名称。

rename_window

参数	类型	描述
target	string	窗口目标：session:window
new_name	string	新名称。

目标格式

所有工具都使用 tmux 标准的 session:window.pane 表示法：

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"

调用 capture_pane 或 send_keys 前，使用 list_sessions → list_windows → list_panes 查找正确的目标。

安装

npm install -g @fr1sk/tmux-mcp

配置

OpenCode（~/.config/opencode/opencode.json）

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

Claude Code（~/.claude/settings.json）

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

Cursor / Windsurf（mcp.json）

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

使用示例

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'

环境变量

在 MCP 客户端配置中的 environment 下设置这些变量，以控制 Agent 行为。

变量	默认值	描述
TMUX_MCP_DEFAULT_SESSION	—	启用 alwaysUseTmux 时，Agent 将命令路由到的会话名称
TMUX_MCP_ALWAYS_USE	false	设置为 "true"，通过 tmux 路由所有 Shell 命令，而不是直接使用 Bash

两者都设置后，get_config 工具会返回一个 instructions 字段，Agent 会使用该字段自动通过配置的会话中的 send_keys 路由每条 Shell 命令。

示例（OpenCode）：

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

安全

此服务通过 tmux 提供不受限制的本地 Shell 访问权限：

• capture_pane — 返回原始终端输出，其中可能包含已打印到终端的环境变量、API 密钥、令牌、数据库密码和 SSH 私钥。
• send_keys — 在目标窗格中执行任意 Shell 命令。AI 发送的任何命令都会以你的权限在 Shell 中运行。
• new_session、new_window 和 split_pane 的 command 参数 — 直接传递给 tmux，由 tmux 通过 $SHELL -c 运行。不进行验证或沙箱隔离。

仅在可信的本地开发环境中使用此服务。切勿将其暴露给可通过网络访问的 MCP 主机或不可信的 AI 助手。

要求

• Node.js 18+
• $PATH 中需包含 tmux