ssh-session-mcp 开源实践：让 AI 助手真正进入远程 SSH 开发流程

在本地代码场景中，Claude、Codex、Cursor 这类 AI 工具已经可以很好地参与代码编写、修改与分析；但在远程开发场景中，尤其是板卡、服务器、GPU 主机和测试机环境下，AI 往往仍然停留在“提供建议”的阶段，难以真正进入终端执行链路。

我开源 ssh-session-mcp，想解决的正是这一段长期存在的断层：

AI 能理解本地代码，却难以稳定、安全地接入远程 SSH 会话。

项目地址：

https://github.com/Zw-awa/ssh-session-mcp

1. 问题背景

目前很多开发者已经形成了这样的工作流：

1. 在本地编辑器中编写和修改代码
2. 借助 AI 分析报错、定位问题、生成修复方案
3. 将代码部署到远程开发板、测试机或 Linux 主机
4. 再通过 SSH 手动执行重启、排障、日志查看等操作

问题在于，前两步是“AI 参与”的，后两步往往又回到了纯人工模式。

于是就出现了几个典型痛点：

1.1 本地上下文与远端上下文割裂

本地聊天窗口、代码仓库、远程终端和日志输出往往分散在不同窗口中，开发者需要频繁做上下文切换。

1.2 AI 无法直接落地远程操作

AI 可能已经准确判断出下一步要执行：

systemctl restart my-service
journalctl -u my-service -n 200

但真正执行这些命令的，仍然是开发者本人。

1.3 终端状态缺乏可观察性

远端终端可能正处于以下任意状态：

1. shell 提示符
2. 密码输入提示
3. 分页器
4. 编辑器
5. 长任务运行中

如果工具无法识别这些状态，就很容易把后续命令发送到错误的位置。

1.4 人与 AI 协作时容易发生输入冲突

在真实场景里，AI 与开发者往往是交替接管终端，而不是单方面独占终端。如果缺少明确的输入控制机制，很容易出现双方同时写入同一终端的问题。

1.5 多设备环境下会话管理复杂

嵌入式或远程开发场景中，通常并不只有一台目标设备。开发板、测试机、远程宿主机、容器节点并存时，命令发错目标是非常现实的风险。

2. 项目定位

ssh-session-mcp 并不是另一个 SSH 客户端，也不是一个大而全的 AI 平台。

它的定位更加聚焦：

作为面向 MCP 客户端的持久化 SSH PTY 会话管理器，为用户和 AI 提供共享的远程终端运行时。

这一定位有两个关键点：

1. 持久化 SSH PTY 会话
2. 用户与 AI 共享同一个终端上下文

项目重点不在于“能否执行远程命令”，而在于“是否能以可协作、可观察、可控制的方式管理远程终端”。

3. 核心能力

围绕上述定位，ssh-session-mcp 当前主要提供以下能力。

3.1 共享 SSH 终端

用户与 AI 共用同一条 SSH PTY，会话状态保持一致，而不是分别建立两份看似相同、实际状态不同的连接。

3.2 浏览器终端接入

项目提供本地浏览器终端，开发者可以直接观察 AI 在远端的操作过程，也可以手动输入命令进行接管。

3.3 输入锁机制

支持 common、user、claude/codex 等模式，用于减少人机协作时的输入冲突。

3.4 安全模式

支持 safe 与 full 两种运行模式。

其中 safe 模式默认会拦截：

1. 明显高风险命令
2. 交互式程序
3. 不会自然结束的流式命令

3.5 智能命令完成判定

ssh-run 不是依赖固定超时，而是结合：

1. prompt 检测
2. idle timeout
3. sentinel 标记

共同判断命令执行是否完成。

3.6 异步长任务跟踪

长时间运行的命令会自动转为异步任务，开发者或 AI 可以继续通过 ssh-command-status 查询执行状态。

3.7 行级历史与会话诊断

项目提供：

1. ssh-session-history
2. ssh-session-diagnostics

用于查看混合历史、当前锁状态、viewer 状态以及运行中的命令信息。

3.8 多设备 profile 管理

通过 ssh-session-mcp.config.json，可以管理多个目标设备及多个命名连接，减少频繁修改 SSH 参数的重复工作。

4. 适用场景

从当前能力边界来看，项目更适合以下场景：

1. 嵌入式与板卡开发
2. 远程 Linux 主机开发
3. 需要频繁查看日志、重启服务、验证部署结果的场景
4. 希望保留人工接管能力的人机协作式终端工作流

如果工作完全发生在本地，项目的价值并不会特别明显；但如果核心运行环境在远端，ssh-session-mcp 更容易体现出作用。

5. 基本使用流程

5.1 安装

可直接通过 npm 安装：

npm install -g ssh-session-mcp

也可以从源码构建：

git clone https://github.com/Zw-awa/ssh-session-mcp.git
cd ssh-session-mcp
npm install
npm run build

5.2 配置

最简单的方式是使用 .env：

SSH_HOST=192.168.1.100
SSH_PORT=22
SSH_USER=username
SSH_PASSWORD=your-password
VIEWER_PORT=auto
SSH_MCP_MODE=safe

如果存在多设备需求，则可以进一步使用 ssh-session-mcp.config.json 管理多个 profile。

5.3 启动

npm run launch

同时还可以使用以下命令进行辅助管理：

npm run status
npm run devices
npm run cleanup

5.4 AI 侧推荐调用方式

推荐的基本流程如下：

ssh-quick-connect -> ssh-run -> 读取输出 -> 决策 -> ssh-run

对于长任务：

ssh-run({ command: "apt update" })
-> async commandId

ssh-command-status({ commandId: "..." })

这一流程的意义在于，AI 不再只是“告诉你命令应该怎么写”，而是可以在约束条件内参与到远程环境操作中。

6. 项目边界

我在设计这个项目时，刻意控制了边界。

ssh-session-mcp 只聚焦 SSH 传输与运行时层，不负责以下内容：

1. 项目业务工作流编排
2. 板卡专用逻辑
3. ROS 业务流程
4. 提示词工程与领域知识组织

换句话说，它更像是一个基础设施组件，而不是业务自动化平台。

我更希望它做好“共享终端、状态管理、锁机制、诊断与配置”这些底层问题，而不是在同一个仓库中混入大量项目特定逻辑。

7. 总结

ssh-session-mcp 想解决的，并不是 SSH 本身，而是 AI 与远程终端之间缺失的那一层协作运行时。

如果把今天很多 AI 编码工具的优势概括为“它们已经非常擅长参与本地开发”，那么这个项目希望补足的就是另一半：

让 AI 在远程 SSH 场景中，也能以更稳定、更可控、更可观察的方式参与工作流。

如果你也在做远程 Linux、板卡、测试机或者服务器相关开发，欢迎直接试用并提出反馈。

如果国内的小伙伴无法连接Github的，可以来同样的持续发行的Gitee下载
https://gitee.com/Zw-awa/ssh-session-mcp