mcp-tmux 是一个综合性的通用 MCP 服务器，用于驱动 tmux，支持在本地机器或通过 SSH 在远程主机上操作。其核心定位是让 AI 代理驱动真实的 tmux 会话，而非私有沙箱环境。当你附着（attach）到代理正在使用的会话时，可以实时看到它的按键输入和命令输出，并能在同一个窗格中输入。这意味着代理的操作对人类完全可见，这一特性被明确作为设计目的而非例外，使 tmux 成为与 AI 结对编程的自然媒介：打开共享会话、观察工作过程、随时接管键盘再交还。由于写入已附着的会话是可见且真实的，使用者需谨慎对待破坏性命令，因为双方在驱动同一个终端。
在能力覆盖上，mcp-tmux 提供经过整理的常用操作工具，并包含一个原生 tmux_command 透传工具，可运行任意 tmux 子命令，因此只要底层 tmux 支持的功能，该服务器都支持。在兼容性方面，它适用于 tmux 1.8+（约 2013 年），几乎覆盖所有活跃发行版；服务器会检测目标上的 tmux 版本，仅使用该版本能理解的标志和格式变量。在运行方式上，任何工具都可以针对本地 tmux 或通过 SSH 的远程主机（临时的 user@host 或配置文件中命名配置文件）运行。旧式或最小化主机只需 tmux 和 ssh；服务器本身运行在具备 Python 3.10+ 的现代主机上。
运行要求：运行服务器的主机需要 Python 3.10+，以及 tmux 二进制（远程目标还需要 ssh）。
安装与注册是分离的步骤：安装软件包只是将 mcp-tmux 可执行文件放到 PATH 中，并不会告知任何 MCP 客户端。由于 Python wheel 无法在安装后运行代码，注册始终是单独的步骤。如果客户端在安装后“找不到”该服务器，通常只是尚未注册。该包可以自行注册，无需手动编辑配置文件。mcp-tmux register 默认使用 --scope user，使服务器对每个目录/会话可见；普通的 claude mcp add tmux -- mcp-tmux 默认使用 local（项目）作用域，这通常是服务器在另一个会话中“不显示”的原因——它只被添加到运行命令的目录中。注册后可用 claude mcp list 确认（应看到 tmux: mcp-tmux - ✓ Connected）。已运行的客户端会话需要重启才能识别新注册的服务器。
工具按工具集分组，以便会话只为所需内容付出 schema 成本。core 始终加载，其余为可选。默认会话加载 core + automation（约 19 个工具）；["all"] 加载完整工具集（61 个）。每个工具接受可选的 target（省略 / "local"、命名配置文件或 user@host）。对于任何专用工具未覆盖的操作——包括被当前激活工具集排除的操作——可使用 tmux_command(args=[...])，它属于 core，可触达每个 tmux 子命令。可通过 toolsets 配置键或 MCP_TMUX_TOOLSETS 环境变量（逗号分隔；环境变量优先于配置）选择工具集。core 始终包含。特殊值 all 加载所有工具集。未知名称会导致启动错误并列出有效工具集。无设置时默认为 ["core", "automation"]。合并类工具使用 kind 判别符而非每个实体一个工具，例如 tmux_kill(kind="window", id="dev:2")。
直播流为可选功能。一次性 CLI 是通用默认方式。若要在窗格产生输出时进行观察（如构建、tail、长任务），tmux_stream_* 会打开持久的控制模式（tmux -C）连接，允许长轮询其事件流，而不是反复调用 tmux_capture_pane。tmux_stream_read 自动推进游标，只需再次调用即可获取下一批；可按窗格和/或类型（"output"、"window-add"、"layout-change" 等）过滤。每个 (target, session) 共享一个连接，tmux_stream_start 是幂等的。只读状态也作为 MCP resources 暴露：tmux://sessions、tmux://{session}/windows、tmux://{window}/panes（本地），以及目标感知变体 tmux://{target}/sessions 等。
关于 send_keys 中文本的求值位置：tmux_send_keys 将其文本输入窗格——它不是本地 shell 命令。因此其中的任何 shell 语法（$(...)、反引号、$VAR、~、通配符等）都由该窗格中运行的 shell 在执行按键时展开，而不是在运行此 MCP 服务器的机器上。对于 SSH 目标，这意味着远程窗格的 shell 执行展开；服务器只传输字面文本（SSH 层对 tmux argv 做 shell 引用，使其完整跨越跳转）。如果需要服务器端的值，请在调用 send_keys 之前自行插值。
可选 TOML 配置位于 ~/.config/mcp-tmux/config.toml（可用 MCP_TMUX_CONFIG 覆盖）。无配置文件时，服务器仍可针对本地 tmux 和任何临时 user@host 目标工作（SSH 选项来自 ~/.ssh/config）。默认情况下，每个 tmux 命令都是一个单独的 tmux 进程（远程目标为 ssh host tmux ...）：本地约 2 ms/命令，LAN 主机约 20 ms。transport = "control"（tmux 3.2+，在 [defaults] 或 [targets.<name>] 表中）改为每个目标维护一个控制模式客户端（tmux -C attach -f no-output,ignore-size）并通过它发送命令：本地约 0.1 ms，LAN 主机约 1 ms。使用它时，tmux_wait_for_text / tmux_wait_for_idle 由窗格输出唤醒而非轮询。代价是该客户端附着到目标的一个会话上：会话显示为已附着（对你亦然），附着使其成为 tmux 最近使用的会话（普通 tmux attach 或无 -t 命令会选择它），无 -t 发送的命令默认发往它，list-clients 会显示该客户端。等待工具在等待期间会向被等待窗格所在会话附着只读客户端。阻塞或作用于客户端本身的命令（wait-for、run-shell、if-shell、attach/detach/switch、kill-server、new-session 等）仍一次性运行，目标无会话时的一切也如此。tmux_transport 工具报告传输方式并可在服务器重启前切换；其描述要求 AI 先询问你。
SSH 连接被多路复用：每次远程调用会添加 -o ControlMaster=auto -o ControlPersist=10m -o ControlPath=<private dir>/ssh-%C，因此只有首次调用某主机会承担 SSH 握手开销。私有目录为 $XDG_RUNTIME_DIR/mcp-tmux-<uid>（或临时目录下同名），权限 0700。配置文件的 ssh_options 可覆盖这三项，ssh_options = ["-o", "ControlMaster=no"] 可为该目标关闭多路复用。
贡献方面，贡献者应阅读 CONTRIBUTING.md 获取完整检查清单（ruff、mypy、pytest）与指南。欢迎在 GitHub 上提交错误报告、功能请求和拉取请求。项目采用 MIT 许可证，版权归 László Pere。
