tmux会话管理工具

tmux mcp rs

tmux-mcp-rs 是tmux的模型上下文协议（MCP）服务器。它允许MCP客户端创建会话、塑造窗口和窗格、运行跟踪命令、检查输出、管理tmux缓冲区，并通过结构化工具而不是脆弱的屏幕抓取来驱动交互式终端程序。

当代理需要真实的TTY、长时间运行的命令、并行窗格、可恢复的终端状态或人类可以在同一任务期间附加的tmux会话时，请使用它。

[！警告] 此服务器可以让MCP客户端运行shell命令、在窗格中键入内容、读取终端输出、修改tmux会话以及读取或写入tmux缓冲区。默认运行时策略是允许的。使用隔离的tmux套接字和 config.toml 在将其暴露给您不完全信任的客户端之前，请先执行策略。

目录

• 服务器提供什么
• 需求
• 安装
• 快速开始
• 客户端配置
• 配置参考
• 安全强化
• MCP工具参考
• MCP资源参考
• 远程和套接字工作流
• 代理工作流模式
• 发展
• 注意事项和限制
• 源锚点

服务器提供什么

• 具有结构化输入和输出的会话、窗口、窗格、客户端和缓冲区工具。
• execute-command 和 get-command-result 用于具有命令ID、资源URI、状态、输出和侧通道退出代码跟踪的shell命令（可选 waitMs；更倾向于资源订阅以完成）。
• 窗格、窗口、会话、客户端、服务器和跟踪命令资源，用于轻量级状态检查，而无需重新运行工具。
• 交互式程序、提示、REPL和TUI的可选原始输入工具。
• 工具筛选、命令筛选、套接字/会话/窗格作用域和粗略操作组的运行时策略控制。
• 编译时功能标志，用于从二进制文件中删除原始输入工具以进行强化构建。
• 可选的SSH路由，以便本地MCP服务器可以控制远程tmux服务器。

MCP路径通常比普通的tmux技能更可靠，因为每个操作都有一个命名的工具、类型化的参数、稳定的ID和结构化的响应。客户端不需要从捕获的文本中推断窗格ID，也不需要解析命令输出来确定命令是否已完成。

需求

• tmux 3.0或更新版本 PATH.
• 从源代码构建时使用Rust 1.70或更高版本。
• 命令跟踪器支持的shell： bash, zsh，或 fish.

启动时，服务器运行 tmux -V。当它检测到tmux 2.x时，它会退出，因为tmux 2.x使用不同的输出格式和分割标志。如果无法检测到版本，启动将继续，受影响的工具调用将报告tmux错误。

安装

货物

cargo install tmux-mcp-rs

家酿

brew install bnomei/tmux-mcp/tmux-mcp-rs

npm

npx @bnomei/tmux-mcp-rs --version
# or: npm install -g @bnomei/tmux-mcp-rs

npm包是一个精简的包装器：在第一次运行时，它下载匹配的GitHub Release二进制文件，验证 .sha256，缓存它，并转发argv。

码头工人

docker run --rm ghcr.io/bnomei/tmux-mcp:0.6.0 --version

图片是 独立的：它包括阿尔卑斯山 tmux 3.x和预构建的musl Linux二进制文件。会话运行 集装箱内，不在桌面tmux服务器上。

• 默认值（推荐用于Docker）： 隔离代理沙盒。人类附着用途 docker exec （见下文）。
• 可选（仅限Linux）： 挂载一个主机tmux套接字，这样容器就可以驱动一个主机端服务器 tmux attach 以本地。macOS/Windows上的Docker Desktop通常无法通过这种方式访问主机Unix套接字。
• 为了便于人/代理在笔记本电脑上共同连接，最好在主机上使用Homebrew、cargo或npm，而不是Docker。

stdio MCP客户端（保持stdin连接）：

docker run --rm -i \
  --name tmux-mcp \
  -v "$PWD:/workspace" \
  ghcr.io/bnomei/tmux-mcp:0.6.0

观看容器内创建的会话：

docker exec -it tmux-mcp tmux attach -t workspace

Linux主机插座接线（高级）：

# host: start an isolated tmux server
tmux -S /tmp/tmux-mcp-agent.sock -f /dev/null new-session -d -s workspace

# container: talk to that socket (image still needs its own tmux client)
docker run --rm -i \
  -v /tmp/tmux-mcp-agent.sock:/tmp/tmux-mcp-agent.sock \
  --user "$(id -u):$(id -g)" \
  ghcr.io/bnomei/tmux-mcp:0.6.0 \
  --socket /tmp/tmux-mcp-agent.sock

# host: attach as usual
tmux -S /tmp/tmux-mcp-agent.sock attach -t workspace

当权限失败时，将容器UID/GID与套接字所有者匹配。更多细节： 包装/README.md.

GitHub发布

从下载预构建的存档 GitHub发布，提取并放置 tmux-mcp-rs 在你的 PATH.

来源

git clone https://github.com/bnomei/tmux-mcp.git
cd tmux-mcp
cargo build --release

二进制文件被写入 target/release/tmux-mcp-rs.

验证安装

tmux -V
tmux-mcp-rs --version

预期产量：

tmux 3.x
tmux-mcp-rs <version>

快速开始

1. 将服务器添加到MCP客户端。

   Codex CLI：

   复制

   codex mcp add tmux -- tmux-mcp-rs
   

   克劳德代码：

   复制

   claude mcp add --transport stdio tmux -- tmux-mcp-rs
   

   通用MCP客户端配置：

   复制

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

2. 在MCP客户端中，要求代理创建或列出tmux会话。

   典型的第一项任务是：

   复制

   Create a tmux session named workspace, list its windows and panes, then run pwd in the first pane.
   

   工具响应应包括会话ID、窗口ID、窗格ID和 commandId 对于被跟踪的命令。

3. 如果您想观看或参与，请附加到同一个tmux会话。

   复制

   tmux attach -t workspace
   

为了更安全地进行多代理工作，请从隔离的套接字而不是默认的tmux服务器开始：

tmux -S /tmp/tmux-mcp-agent.sock -f /dev/null new-session -d -s workspace
tmux -S /tmp/tmux-mcp-agent.sock attach -t workspace

然后配置MCP服务器 --socket /tmp/tmux-mcp-agent.sock, TMUX_MCP_SOCKET=/tmp/tmux-mcp-agent.sock，或每个工具 socket 以（权力）否决

客户端配置

使用 args 当您的MCP客户端接受JSON配置时：

{
  "mcpServers": {
    "tmux": {
      "command": "tmux-mcp-rs",
      "args": [
        "--shell-type",
        "zsh",
        "--socket",
        "/tmp/tmux-mcp-agent.sock",
        "--config",
        "/path/to/config.toml"
      ]
    }
  }
}

对于远程tmux服务器，添加 --ssh:

{
  "mcpServers": {
    "tmux": {
      "command": "tmux-mcp-rs",
      "args": [
        "--ssh",
        "user@host",
        "--socket",
        "/tmp/tmux-mcp-agent.sock"
      ]
    }
  }
}

除以下工具外的所有MCP工具 socket-for-path 接受可选 socket 参数。如果工具省略了它，服务器将使用进程默认套接字。

配置参考

tmux-mcp-rs 不自动加载配置文件。通过一个 --config /path/to/config.toml.

CLI选项

环境变量

优先级规则：

配置示例

[shell]
type = "zsh"

[ssh]
remote = "user@host"

[security]
enabled = true
allow_execute_command = true
allow_raw_mode = true
allow_send_keys = false
allow_kill = true
allow_create = true
allow_split = true
allow_rename = true
allow_move = true
allow_capture = true
allow_list = true
allowed_sockets = ["/tmp/tmux-mcp-agent.sock"]
allowed_sessions = ["workspace"]
allowed_panes = ["%1"]
allowed_buffer_paths = ["/srv/tmux-mcp-buffers"]

[security.command_filter]
mode = "allowlist"
patterns = ["^cargo ", "^git ", "^rg ", "^sed "]

[security.tools]
mode = "deny"
items = ["@raw-input"]

[tracking]
capture_initial_lines = 1000
capture_max_lines = 16000
completed_retention_minutes = 240
completed_max_entries = 1000
tracking_deadline_seconds = 600

[search]
streaming_threshold_bytes = 262144

安全选项

security.command_filter 检查每个非空shell语句 execute-command, send-keys （字面和非字面）， paste-text, set-buffer, append-buffer，并将解码后的字节传递给 send-hex.它拆分为非上市 ;, |, &，和换行符，然后递归检查命令替换、进程替换、子shell和大括号组。它拒绝接受无法安全分析的壳体形式，包括ANSI-C $'...' 引用和shell -c 包装纸。它不会筛选特殊的密钥助手。对于硬边界，请在运行时禁用原始输入工具或将其编译出来。

跟踪选项

搜索选项

安全强化

默认情况下，策略强制已启用，但允许：

• 全部粗糙 allow_* 大门是 true.
• command_filter.mode 是 off.
• allowed_sockets, allowed_sessions, allowed_panes，以及 allowed_buffer_paths 未设置。缓冲区文件操作仍然仅限于默认的临时目录沙盒。
• [security.tools] 是拒绝模式，没有被拒绝的项目。

该默认值便于本地实验，但它不是沙箱。

使用隔离的tmux套接字

tmux -S /tmp/tmux-mcp-agent.sock -f /dev/null new-session -d -s workspace
tmux-mcp-rs --socket /tmp/tmux-mcp-agent.sock --config config.toml

[security]
allowed_sockets = ["/tmp/tmux-mcp-agent.sock"]

当 allowed_sockets 如果已设置，则没有显式套接字的调用仍将解析为进程默认套接字，并且必须与allowlist匹配。

在运行时删除原始输入

[security]
allow_send_keys = false

[security.tools]
mode = "deny"
items = ["@raw-input"]

当shell输入应该通过时使用此选项 execute-command 因此，命令过滤和命令结果跟踪仍然是核心。

仅显示读取工具和跟踪的命令执行

[security.tools]
mode = "allow"
items = ["@read", "execute-command"]

@read 包括 get-command-result，列出工具、捕获工具、缓冲区读取/搜索工具，以及 socket-for-path.

覆盖一个工序的刀具表面

TMUX_MCP_TOOLS=send-keys,paste-text tmux-mcp-rs
TMUX_MCP_TOOLS=deny:@raw-input tmux-mcp-rs
TMUX_MCP_TOOLS=allow:@read,execute-command tmux-mcp-rs

编译原始输入工具

默认的Cargo功能集包括 interactive 和 special-keys.

• interactive 寄存器 send-keys, send-hex，以及 paste-text.
• special-keys 寄存器 send-cancel, send-eof, send-escape, send-enter, send-tab, send-backspace, send-up, send-down, send-left, send-right, send-page-up, send-page-down, send-home，以及 send-end.

禁用这些功能以从二进制文件中删除工具：

# Filtered-only build: execute-command is the only shell-input path.
cargo build --release --no-default-features --features rayon,rapidfuzz

# Keep raw keystrokes but remove special-key helpers.
cargo build --release --no-default-features --features rayon,rapidfuzz,interactive

execute-command 始终已注册，并仍受 security.command_filter.

MCP工具参考

工具可用性取决于Cargo功能和运行时策略。运行时被拒绝的工具将从通告的MCP工具列表中删除，并在调用时被拒绝。

工具组

按任务列出的工具

更喜欢 execute-command 使用资源订阅/读取（或 get-command-result + waitMs)用于非交互式命令。每个窗格都有跟踪的命令队列。使用 capture-pane 只为实时进步；不要将窗格“完成”标记视为权威。仅将原始输入工具用于提示、REPL、编辑器、寻呼机和TUI，而不是在该窗格上运行跟踪命令时使用。

跟踪命令快照使用情况 schemaVersion: 1 目前正在通过 queued, running那么 completed, failed，或 tracking_error。该方案还保留 cancelled，但当前跟踪器不会发出它。正常的跟踪命令会拒绝嵌入的换行符、未加引号的shell注释标记(#)，以及未报价的后台操作员(&)因为这些表格可以绕过跟踪尾声。集 rawMode=true 或 noEnter=true 仅当您有意禁用侧通道完成跟踪时；这些记录仍然存在 running.

show-buffer 默认情况下最多读取65536个字节。 search-buffer 默认为每个缓冲区40个上下文字节、50个匹配项和65536个扫描字节；它返回字节偏移量，并在结果被截断时恢复游标。文字和正则表达式搜索始终可用。模糊匹配和相似性得分要求 rapidfuzz 货物功能，默认启用。

MCP资源参考

服务器、窗格、窗口、会话和客户端资源反映了服务器的默认套接字。被跟踪的命令资源保留其原始记录的有效套接字 execute-command，包括每个刀具插座的超控。资源由当前安全策略动态枚举和过滤。

仅支持跟踪命令结果资源 resources/subscribe；在a之后读取资源 notifications/resources/updated 活动。其他资源URI提供按需快照。

远程和套接字工作流

远程SSH

使用 --ssh 在另一台机器上运行tmux命令。SSH身份验证必须是非交互式的，例如基于代理或密钥的登录。

tmux-mcp-rs --ssh "user@host"

在目标之前传递SSH选项：

tmux-mcp-rs --ssh "-i ~/.ssh/key user@host"

连接字符串使用shell单词规则进行拆分。目标应该是最后一个令牌。服务器在将远程tmux命令发送到SSH之前会引用它，当可以访问远程tmux时，tmux版本检查会应用于远程tmux。

远程加隔离插座

在远程主机上创建专用tmux服务器：

ssh user@host 'tmux -S /tmp/tmux-mcp-agent.sock -f /dev/null new-session -d -s workspace'

针对该远程套接字启动本地MCP服务器：

tmux-mcp-rs --ssh "user@host" --socket /tmp/tmux-mcp-agent.sock

需要时直接从外壳连接：

ssh -t user@host 'tmux -S /tmp/tmux-mcp-agent.sock attach -t workspace'

插座隔离

使用 --socket 或 TMUX_MCP_SOCKET 要在一个tmux服务器上保留一个代理：

tmux-mcp-rs --socket /tmp/tmux-mcp-agent.sock

TMUX_MCP_SOCKET=/tmp/tmux-mcp-agent.sock tmux-mcp-rs

在MCP客户端启动之前，如果您想要一个人类可见的工作区，请预先创建会话：

tmux -S /tmp/tmux-mcp-agent.sock -f /dev/null new-session -d -s workspace
TMUX_MCP_SOCKET=/tmp/tmux-mcp-agent.sock tmux-mcp-rs

Docker和套接字

GHCR映像包括tmux 3.x，默认为 独立的 容器内的会话(docker exec … tmux attach).仅在Linux上，您可以挂载主机套接字，以便容器MCP服务器驱动主机tmux服务器——请参阅 安装→ 码头工人 和 包装/README.mdmacOS/Windows上的Docker Desktop不是可靠的主机套接字路径；当您需要轻松的本地协同连接时，请使用本机安装。

代理工作流模式

集成测试涵盖了以下tmux工作流：

对于面向代理的tmux工作流，请参阅：

• 通过mcp实现tmux
• tmux缓冲区资源管理器

tmux-buffer-explorer 使用tmux缓冲区作为大文本的外部搜索空间。当代理需要有界搜索和后续切片，而不是将整个缓冲区加载到上下文中时，它很有用。

发展

构建二进制文件：

cargo build --release

运行不需要tmux的单元测试：

cargo test --lib
cargo test --test cli
cargo test --test search

运行tmux支持的集成测试：

TMUX_MCP_INTEGRATION=1 cargo test --test integration

集成测试使用临时套接字创建隔离的tmux服务器，并在之后对其进行清理。

运行与CI相同的Rust检查：

cargo fmt --all -- --check
cargo clippy --all-targets --all-features -- -D warnings
cargo test --all-targets

发布说明和发布包装详细信息实时发布 更改日志.md 和 docs/RELEASE.md.

注意事项和限制

• tmux拥有粘贴缓冲区，而此服务器在内存中保留跟踪的命令快照。 paste-text, set-buffer, append-buffer，并且大的保留命令输出仍然会消耗主机内存。跟踪的输出由以下内容限制 capture_max_lines，但保留的字符串和单个行长度不受字节限制。
• 缓冲区搜索通过临时文件流式传输大缓冲区 search.streaming_threshold_bytes，但tmux缓冲区本身并不是按大小驱逐的。
• tmux行从制表符分隔的行中解析 -F 输出。窗格标题、路径或类似字段内的文字选项卡可能会移动后面的字段，并产生格式错误或跳过的行。
• paste-text 使用括号内的粘贴标记。不支持括号粘贴的shell和程序可能会将嵌入的换行符视为Enter。在macOS上，默认 /bin/bash 3.2不支持现代括号粘贴行为；zsh或更新的bash对于不应该逐行提交的多行输入更安全。
• save-buffer 写入tmux服务器文件系统，以及 load-buffer 从中读取。两者都受 allow_capture, [security.tools]，以及 security.allowed_buffer_paths。在默认启用策略的情况下，调用者使用本地临时目录中的相对路径 tmux-mcp-buffers/ 沙箱或 /tmp/tmux-mcp-buffers/ 通过SSH；父遍历和规范或符号链接转义被拒绝。
• 命令结果是套接字绑定的。 get-command-result 必须使用与原始插座相同的有效插座 execute-command 电话。
• 跟踪命令完成使用专用tmux出口缓冲区+ wait-for 信号，不可伪造的窗格滚动。可选的开始/完成行仅适用于人工/调试。
• 交互式 send-keys/paste-text 在同一窗格上跟踪运行期间未定义；等待命令完成或使用另一个窗格。
• 端到端SSH行为是手动验证的，因为CI不提供远程主机。

源锚点

• CLI解析和启动行为： src/main.rs
• MCP工具、资源和服务器说明： src/server.rs
• 安全策略和工具组： src/security.rs
• 命令跟踪： src/commands.rs
• tmux套接字、SSH和进程包装器行为： src/tmux.rs
• 公共数据类型： src/types.rs
• CLI测试： tests/cli.rs
• 集成工作流程： 测试/集成.rs
• 缓冲区搜索测试： tests/search.rs

许可证

MIT许可证。看 许可证.