AI导哈

tmux代理服务

为Cursor的Model Context Protocol构建的tmux代理，用于在远程tmux会话中执行命令、捕获输出并保持完整的历史记录。

  • by heaus
  • Python
  • 本地部署
  • 更新于
在 GitHub 查看 heaus/tmux_mcp

使用说明

Cursor MCP tmux 代理（博通内部使用）

tmux MCP代理是专为Cursor的模型上下文协议（Model Context Protocol）构建的，旨在用于博通（BRCM）的内部工作流程。它为Cursor在远程tmux会话中提供了一个持久的立足点，使助手能够发出命令、捕获输出，并保持对其所有操作的完全可审计历史记录。

代理为每个配置文件打开一个单独的Paramiko SSH连接，并在每次tmux交互时重用该连接。这样可以保持命令延迟低，并避免反复创建本地进程 ssh 过程。

要求

  • 操作系统：macOS 或支持 WSL 的 Windows（由于代理需要本地安装的 Python 工具链和包，因此无法在我们的 VDI 环境中运行）。
  • 在运行 Cursor 的机器上安装 Python 3.11 或更高版本。
  • 一个可访问的远程主机，具有：
    • ssh 访问。
    • tmux 已安装且可发现于 PATH。
  • （可选）在（某处）定义的主机别名 ~/.ssh/config 因此，代理可以自动加载配置文件。

安装

Python 版本和环境

这个（或：那个） python -m venv .venv 命令要求 Python 在（指定位置）创建一个虚拟环境 .venv/ 目录，以防止代理的依赖项泄露到您的全局解释器中。该代理已在 Python 3.11.11 上进行测试。

如果你特别需要 Python 3.11.11：

  • macOS（发音：/ˈmækOS/） – 使用 Homebrew 全局安装它brew install python@3.11）。
  • WSL / Linux（Windows Subsystem for Linux / Linux） – 通过你的包管理器进行安装（例如。 sudo add-apt-repository ppa:deadsnakes/ppa && sudo apt install python3.11 python3.11-venv）。

软件包安装

  1. 将此包复制到您的目标目录中。

  2. 在该目录内创建一个独立的Python环境，并安装运行时依赖项（替换 <your_directory> （以及你解压源代码的绝对路径）：

    cd <your_directory>/tmux_mcp
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

光标MCP设置

该套餐包括 .cursor/mcp.json，该（系统/程序）将代理注册为Cursor中的一个 stdio MCP服务器。在Cursor中打开工作区，它将自动启动代理。如果您需要更改命令、环境变量或工作目录，请在打开项目之前编辑该文件。

如果你正在与另一个MCP客户端进行集成，你可以使用以下模板。替换 <your_directory> 使用与上述相同的绝对路径，以便MCP主机直接执行虚拟环境解释器和启动脚本：

{
  "mcpServers": {
    "tmux-mcp-agent": {
      "type": "stdio",
      "command": "<your_directory>/tmux_mcp/.venv/bin/python",
      "args": [
        "<your_directory>/tmux_mcp/scripts/start_mcp_agent.py",
        "--log-level", "INFO",
        "--session", "cursor-shared",
        "--window", "agent",
        "--pane", "0"
      ]
    }
  }
}

将JSON文件放置在您的MCP主机期望服务器定义的位置，并确保 tmux_mcp 该包可被导入。

顶级字段的含义是：

  • type – 必须留下 stdio光标通过标准输入/输出（stdin/stdout）与代理进行通信。
  • command – 启动代理程序的Python解释器的绝对路径（通常为 .venv/bin/python （在这个项目中）。
  • args – 传递给该解释器的参数的有序列表。第一个元素应该是启动脚本，其后是你想要传递的任何命令行界面（CLI）标志。

MCP服务器参数

启动脚本 scripts/start_mcp_agent.py 将CLI选项转发给 tmux_mcp.agent你可以调整其中的任何一项 args 数组：

  • --log-level – 日志详细程度（DEBUG， INFO， WARNING， ERROR）。
  • --session – 默认创建/附加的 tmux 会话（默认： cursor-shared）。
  • --window – 默认的 tmux 窗口名称（默认： agent）。
  • --pane – 默认的 tmux 窗格标识符（默认： 0）。
  • --log – 结构化日志文件的路径（默认： logs/agent_activity.log）。

根据需要添加或删除选项；在启动MCP服务器时，光标将原样传递这些选项。

使用 tmux 会话

  1. 使用 list_profiles 并且 upsert_profile 用于管理加密SSH连接配置文件的工具。仅提供 name 并且 source_host 当主机存在时，这就足够了 ~/.ssh/config代理将自动继承主机名、用户、端口、身份文件以及常用选项。
  2. Cursor 通常会调用 health_check 随后是 connect_session提供配置文件名以及所需的tmux（终端多路复用器）设置 session， window，以及可选的 pane 标识符。
  3. 要执行命令，请调用 submit_command如果安全模式标记了一条命令，请回复： approve_command 或者 reject_command 使用返回的 command_id.
  4. 随时从任意面板中检索实时上下文 read_context。

示例（光标聊天提示）

Connect to the tmux server using profile "staging", session "cursor", window "agent".

Cursor 会将这条信息翻译成 connect_session 工具调用：

{
  "profile": "staging",
  "session": "cursor",
  "window": "agent"
}

一旦连接成功，您可以根据提示进行后续操作，例如“运行 npm test “在当前面板中”，然后代理将通过……发送该命令 submit_command。

示例（创建或更新配置文件）

Create an SSH profile called "staging" for host 203.0.113.15 using user "deploy" and key file "/Users/bo/keys/staging.pem".

Cursor将其转化为一个 upsert_profile 类似于工具调用：

{
  "profile": {
    "name": "staging",
    "hostname": "203.0.113.15",
    "username": "deploy",
    "identity_file": "/Users/bo/keys/staging.pem"
  }
}

随后的“连接到预发布环境”提示会自动重用已存储的配置文件。呼叫（或：执行操作） upsert_profile 再次以同样的方式 name 当凭据或端口更改时，覆盖它们。

代理确保目标会话和窗口存在，必要时创建它们，并保持一个持久的面板快照，以便仅报告每次命令后的差异。

日志记录与审计

每一个命令、审批决定以及捕获的输出增量都会被附加到 logs/agent_activity.log 作为JSON Lines格式。每条记录都包含Cursor任务标识符以及tmux会话/窗口/面板信息，这使得追踪共享同一tmux会话的并行任务变得容易。

故障排除

  • Paramiko TripleDES 警告 – 当前的Paramiko版本仍然引用了TripleDES。密码学库已将其标记为已弃用，因此您可能会看到 CryptographyDeprecationWarning 在日志中。这是一个无害的警告；较新版本的Paramiko会自动移除旧的加密算法。
  • SSH连接问题 – 确认配置文件的身份文件在本地存在，并且任何（相关设置或数据） ProxyCommand 或者 IdentitiesOnly 选项是有效的。代理通过（某种方式）将这些错误报告回来 SessionError 信息。
  • 未找到 tmux – 确保 tmux 已安装在远程主机上，并且在SSH会话所暴露的PATH中可用。

定制化

  • 默认功能标志位于 src/tmux_mcp/config/feature-flags.yaml调整它们以改变安全模式行为或审批模式。
  • 能力定义如下 src/tmux_mcp/config/capabilities.json如果您添加了或重命名了工具/资源，请更新此文件。
  • 当你手动添加新的连接配置文件时，请记住，代理会使用Fernet在磁盘上以加密形式存储它们；删除时 .tmux_mcp/ 将删除本地缓存的配置文件。

支持

如果Cursor报告MCP服务器不可用，请运行 python -m tmux_mcp.agent --log-level DEBUG 从终端查看启动日志。如果需要进一步帮助，请附上收集的日志提交一个问题。

相关 MCP