Mcp Remote Ssh

mcp-remote-ssh

为 AI Agent 提供完整 SSH 访问能力的 MCP 服务——支持持久会话、结构化命令输出、SFTP 文件传输、端口转发、会话记录，以及安全注入环境变量并自动脱敏输出。

为什么需要它

其他 SSH MCP 服务各有缺失：不支持密码身份验证、持久会话、SFTP、端口转发或结构化退出代码。而这个服务全部支持——还提供了唯一一种 MCP 级别的机密管理机制，可防止 AI Agent 看到你的凭据。

安全注入环境变量

**问题：**当 AI Agent 需要在远程服务器上使用 API 令牌、密码或密钥时，常规做法会将机密暴露在大模型的上下文窗口中。Agent 要么读取机密文件（机密就此进入对话），要么运行 echo $TOKEN 并在输出中看到机密值。

解决方案：ssh_load_env_file 会从你本机上的文件读取机密，将其注入远程 SSH 会话，并将其登记为自动脱敏内容。AI Agent 可以自由使用这些变量——每条工具响应都会先经过清理，再发送给大模型。

# Agent calls this -- file is read from YOUR machine, not the remote host
ssh_load_env_file(session_id="abc", file_path="~/.secrets/prod.env")
→ "Loaded 3 variables from local:~/.secrets/prod.env: API_TOKEN, DB_PASS, SECRET_KEY"

# Agent tries to echo the value -- redacted automatically
ssh_execute(session_id="abc", command="echo $API_TOKEN")
→ {"stdout": "***\n", "exit_code": 0}

# Agent dumps the environment -- all secret values scrubbed
ssh_execute(session_id="abc", command="env | grep API_TOKEN")
→ {"stdout": "API_TOKEN=***\n", "exit_code": 0}

# Agent reads a file containing a secret -- also redacted
ssh_read_remote_file(session_id="abc", remote_path="/etc/app/config")
→ "db_password=***\ndb_host=localhost\n"

# Normal commands work perfectly -- no over-redaction
ssh_execute(session_id="abc", command="uname -a")
→ {"stdout": "Linux server 6.1.0 ...", "exit_code": 0}

工作原理

┌─────────┐         ┌──────────────────────────────┐         ┌─────────────┐
│   LLM   │ ←─JSON─ │   MCP Server (your machine)  │ ──SSH─→ │ Remote Host │
│ (Agent) │         │                              │         │             │
└─────────┘         │  1. Reads ~/.secrets/prod.env│         └─────────────┘
                    │  2. Parses KEY=VALUE pairs   │
                    │  3. Stores values in memory  │
                    │  4. Injects into SSH session │
                    │  5. Redacts ALL tool output  │
                    └──────────────────────────────┘

1. 读取本地文件——环境变量文件位于你的本机上，不会出现在远程主机
2. 通过 Shell 内置命令注入——使用 read -r VAR <<< 'value' && export VAR（不会暴露进程树）
3. 基于标准输入注入执行命令——ssh_execute 通过标准输入将机密传递给 bash 包装器，因此它们不会出现在 /proc/*/cmdline 中
4. 自动脱敏——每条工具响应（ssh_execute、ssh_shell_send、ssh_shell_read、ssh_read_remote_file）都会先经过清理，再发送给大模型
5. 优先匹配最长字符串——避免部分匹配造成内容损坏（例如，先替换 abc123，再替换 abc）

安全属性

威胁	是否缓解？	方式
机密出现在大模型上下文窗口中	是	将输出中的机密值替换为 ***
机密出现在远程进程树中（Shell）	是	Shell 内置命令（read/export）不会派生进程
机密出现在远程进程树中（执行命令）	是	机密通过标准输入传递，不会出现在 /proc/*/cmdline 中
大模型尝试对环境变量文件运行 cat	不适用	文件仅位于本地，远程不存在
大模型尝试运行 echo $VAR	是	输出会经过脱敏
对机密进行编码或转换（Base64）	否	只对字面匹配项进行脱敏
首次 SSH 连接遭受中间人攻击	可接受	使用了 AutoAddPolicy——参见下方说明

主机密钥策略

此服务使用 Paramiko 的 AutoAddPolicy——未知主机密钥会直接接受，不会提示确认。这是有意为之，适用于主机生命周期短暂的 QE/实验室环境（Beaker、云实例、CI 机器）。取舍如下：

• **优点：**连接新配置的机器无需任何操作
• **缺点：**首次连接未知主机时容易遭受中间人攻击

如果你在不可信网络上操作，可考虑通过 VPN 或预先分发主机密钥的 SSH 堡垒机转发连接。未来版本可能会为安全要求严格的环境添加 host_key_policy 参数。

环境变量文件格式

标准 .env 格式：

# Comments are ignored
API_TOKEN=your-secret-token
DB_PASSWORD="quoted values work"
SECRET_KEY='single quotes too'
export ALSO_WORKS=yes

会话记录

默认情况下不启用记录。需要审计 Agent 实际运行的内容时，可按会话启用——有助于复现 Bug 和开展测试活动。

# Start recording on connect
ssh_connect(host="lab.example.com", username="root", password="...", record=True)

# Or toggle later
ssh_start_recording(session_id="a1b2c3d4")
ssh_execute(session_id="a1b2c3d4", command="uname -a")
ssh_get_transcript(session_id="a1b2c3d4")
→ {"recording": true, "total_entries": 2, "transcript": "[12:01:02] --- connect: lab.example.com ---\n[12:01:05] $ uname -a\nLinux ...\n[exit 0]"}

ssh_save_transcript(session_id="a1b2c3d4", path="/tmp/lab-session.log")
ssh_stop_recording(session_id="a1b2c3d4")

• 执行命令／sudo 的输出以及 Shell 发送／读取的 I/O，在记录前都会进行机密脱敏
• 关闭会话会丢弃内存中的记录——请先调用 ssh_save_transcript 或 ssh_get_transcript

安装

uvx mcp-remote-ssh        # or: pip install mcp-remote-ssh

配置

{
  "mcpServers": {
    "remote-ssh": {
      "command": "uvx",
      "args": ["mcp-remote-ssh"]
    }
  }
}

工具（24）

连接

工具	描述
ssh_connect	使用密码、密钥或 Agent 身份验证进行连接。可选设置 record=True，立即开始记录会话。返回 session_id
ssh_list_sessions	列出活动会话
ssh_close_session	关闭会话并释放资源

执行

工具	描述
ssh_execute	运行命令，返回 {stdout, stderr, exit_code}
ssh_sudo_execute	以 sudo 提权运行命令

交互式 Shell

工具	描述
ssh_shell_open	打开持久 Shell（保留当前工作目录、环境变量和进程）
ssh_shell_send	发送文本（可选按下 Enter）
ssh_shell_read	读取当前输出缓冲区
ssh_shell_send_control	发送 Ctrl+C、Ctrl+D 等控制信号
ssh_shell_wait	等待匹配某个模式或输出稳定

密钥管理

工具	描述
ssh_load_env_file	从本地环境变量文件加载密钥；值不会返回给大模型
ssh_clear_secrets	清除脱敏注册表（值将再次可见）

会话记录

工具	描述
ssh_start_recording	开始记录此会话的 execute/sudo/shell I/O
ssh_stop_recording	停止记录；会话关闭前，会话记录仍可访问
ssh_get_transcript	以文本或 JSONL 格式返回会话记录（last_n 可选）
ssh_save_transcript	将会话记录写入 MCP 主机上的本地文件

SFTP

工具	描述
ssh_upload_file	将本地文件上传到远程主机
ssh_download_file	将远程文件下载到本地机器
ssh_read_remote_file	读取远程文本文件
ssh_write_remote_file	写入远程文件或向其追加内容
ssh_list_remote_dir	列出目录及元数据

端口转发

工具	描述
ssh_forward_port	创建 SSH 隧道（本地 -> 远程）
ssh_list_forwards	列出活动隧道
ssh_close_forward	关闭隧道

快速开始

ssh_connect(host="server.example.com", username="admin", password="secret", record=True)
→ {"session_id": "a1b2c3d4", "connected": true, "recording": true}

ssh_load_env_file(session_id="a1b2c3d4", file_path="~/.secrets/prod.env")
→ "Loaded 2 variables: API_TOKEN, DB_PASS"

ssh_execute(session_id="a1b2c3d4", command="curl -H \"Authorization: Bearer $API_TOKEN\" https://api.example.com")
→ {"stdout": "{\"status\": \"ok\"}", "exit_code": 0}  # token used but never visible

ssh_shell_open(session_id="a1b2c3d4")
ssh_shell_send(session_id="a1b2c3d4", data="cd /opt && make -j$(nproc)")
ssh_shell_wait(session_id="a1b2c3d4", pattern="$ ", timeout=600)

ssh_upload_file(session_id="a1b2c3d4", local_path="config.yaml", remote_path="/etc/app/config.yaml")
ssh_forward_port(session_id="a1b2c3d4", remote_port=5432, local_port=15432)

设计

基于 Paramiko（SSH）和 FastMCP（MCP 协议）构建。

• ssh_execute 使用 exec_command()，提供清晰的结构化输出和真实退出码
• 加载密钥后，ssh_execute 会通过 stdin 将导出语句传递给 bash 包装器，然后使用 exec 执行实际命令——密钥不会出现在进程树中
• ssh_shell_* 使用 invoke_shell() 创建持久交互式会话
• 所有阻塞的 Paramiko 调用都在 run_in_executor 中运行，以保持异步
• Shell 会维护 500KB 的滚动缓冲区，供 shell_read 轮询
• 密钥脱敏会在所有输出路径中按字符串长度从长到短进行替换
• 会话记录保存在内存中，默认关闭，并会在会话关闭时丢弃

许可证

MIT