# mcp-ssh

**Repository Path**: self-testing-oxchen/mcp-ssh

## Basic Information

- **Project Name**: mcp-ssh
- **Description**: 创造一个给智能开发工具使用的SSH工具，具备安全隔离，智能开发工具自动部署，适配ClaudeCode、Opencode、Hermess、Codex、Qoder、Codebuddy、ZCode
- **Primary Language**: JavaScript
- **License**: AGPL-3.0
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2026-07-30
- **Last Updated**: 2026-08-25

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# mcp-ssh

一个 **MCP (Model Context Protocol) 服务器**,封装 SSH/SFTP,通过 **Streamable HTTP** 暴露给开发工具(opencode / claude code)。配有一个 **Electron + React 桌面应用** 用于管理服务器、项目与安全策略。

核心价值:**开发工具全程不接触账号密码**,且危险命令/越界路径被**策略**自动拦截;主密码仅由人工在界面输入、只存内存、不落盘,堵上"LLM 翻配置文件窃取凭证"的漏洞。

## 工作方式

1. 首次启动:应用检测到无主密码 → 强制**设置主密码**向导(否则不能进入)。
2. 之后每次启动:必须先**人工输入主密码解锁**(全屏解锁门,仅内存,不落盘)。删除 `data/credentials.enc` 即重置(服务器配置随之清空)。
3. 在"服务器"页配置服务器**连接信息**(host/port/user/密码或私钥)——服务器只管连接,不含任何策略。每行有**测试**(试连)与 **cmd**(打开终端窗口直连 Linux)按钮。
4. 在"设置"页的"命令策略/路径策略"标签里管理策略:默认策略 `default_cmd_policy` / `default_dir_policy`(可查看可改不可删),也可新增/复制/改名/删除自定义策略。策略通过**不可变 id** 绑定,改名不影响已绑定项目。
5. 在"项目"页配置项目:指明**绑定哪个服务器 + 部署路径 + 命令策略 + 路径策略**(一个服务器可绑多个项目,路径各不同,策略可不同)。
6. 在"服务"页启动 MCP 服务(固定 `http://127.0.0.1:54110/mcp`)。**Token 管理**:可创建多个 Token,每个绑定一个项目(只能操作该项目绑定的服务器),有效期 1/3/7/30/90 天,可延长/刷新/删除,持久化保存;一键复制 Claude/OpenCode/Codex 配置。解锁即自动启动服务,锁定软件不关闭 MCP 服务。
7. 开发工具/LLM 通过 HTTP 调用工具完成部署、运维 —— 自动受项目绑定策略约束。

## 特性

- **Streamable HTTP** 传输(固定端口 `54110`,仅本机 `127.0.0.1`,Bearer Token 鉴权)
- **Electron + React/Vite** 桌面 UI:启动解锁门、服务器 CRUD(可禁用/启用)、项目 CRUD(可禁用/启用)、策略 CRUD、服务启停、命令日志查看
- SSH `ssh_exec`、SFTP(list/stat/read/write/mkdir/delete/upload/download)、`deploy_project` 组合工具 + `list_policies`
- 凭证 **AES-256-GCM** 加密存储于执行目录 `data/credentials.enc`(仅连接信息)
- **主密码每次启动人工输入,仅内存,不落盘、不进 env**
- **策略与凭证解耦**:服务器=纯连接;命令/路径策略按 id 绑定到项目,默认策略内置且可编辑不可删
- 路径围栏(项目 `deployPath` + 策略 `allowedPaths`)+ 阻止敏感路径 + 防 `../` 遍历
- 输出脱敏 + 命令日志
- 配置/凭证/日志全部位于执行目录 `data/`(便携)
- **设置页**:主题切换(深色/浅色/跟随系统)、修改主密码(重加密全部凭证)、无操作自动锁定(可设超时,0=关闭)、离线安装包目录(供服务器页「状态」离线安装 docker/telnet)、命令策略管理、路径策略管理、关闭按钮行为(退到任务栏=默认/退出程序)、配置导入/导出(导出需主密码解密,明文 JSON 含凭证)
- **服务器测试/cmd**:添加服务器后可一键测试连接;cmd 按钮打开 xterm 终端窗口,用已解密凭证直连 Linux(无需 sshpass/暴露密码;属拥有者手动操作,不受策略约束)。**禁用态**:服务器/项目可一键禁用(保留配置/凭证,AI 工具操作被拦截,需启用后恢复),禁用的服务器在列表标记「已禁用」且不进行健康检查
- **Token 管理**:多 Token,每个绑定项目(限操作该项目绑定的服务器),有效期可延长/刷新/删除,持久化;过期不自动换值
- **审批模式**:命令策略可选 approval 模式(白名单放行 · 黑名单拦截 · 其余待人工审批);新增 `request_command` / `list_approval_requests` 工具
- **默认 allowlist 预置**:docker/k8s/只读命令自动回填到默认策略并在界面展示
- **全局禁止 mkdir/touch**:文件与目录新建只能走 SFTP,`ssh_exec` 不允许新建
- **服务器健康状态**:列表间隔 10 分钟自动检测,显示最近检查时间
- **系统任务栏(托盘)**:软件常驻系统托盘,点击右上角 × 默认退到任务栏(而非退出程序)并自动锁定(清除内存凭证,MCP 服务保持运行),再次点击托盘恢复后需重新输入主密码。托盘右键菜单提供:显示主窗口、服务启停、服务状态显示、审批申请数量、退出软件。可在设置页「关闭按钮行为」改为退出程序。从托盘停止服务时显示「服务停止中…」状态,等待端口释放后才可重启
- **服务器状态探针 + 离线安装**:服务器列表每行新增「状态」按钮,弹框显示系统基本信息(CPU/内存/磁盘/内核/发行版)、运行信息(进程/负载/uptime)、软件安装信息(docker/docker-compose 版本与存储目录、telnet);未安装时可一键离线安装——弹框输入 root 密码,本程序通过 SFTP 上传离线包(centos7 用 rpm 离线安装 docker-ce 26.1.4 + telnet;ubuntu22 用 deb 离线安装 docker-ce 29.7.1 + telnet)并实时显示安装进度。离线包目录在设置页配置(需含 centos7/ 与 ubuntu22/ 子目录),不随安装包发布。属拥有者手动操作,不暴露给 AI
- **命令日志**:含项目字段、3 个月滚动清除、一键清空、按结果(success/allow/deny/error)过滤、分页浏览
- **悬浮提示 + 自定义确认框**:toast 浮层不挤占布局;确认弹框为界面内模态框(不触发原生 confirm 焦点劫持)
- **无顶部菜单栏**:左上角显示 `mcp-ssh` + 版本号

## 快速开始

```bash
npm install
npm run build        # 构建 lib + electron 主进程/渲染层
npm run start         # 启动 Electron 应用(或 npm run dev 开发热重载)
npm run dist:win     # 打包成 Windows 安装包(setup.exe)
```

> 不想自行构建?Windows 用户可直接使用预构建的 **安装包**(`release/mcp-ssh-<version>-setup.exe`):双击安装后从开始菜单/桌面「mcp-ssh」快捷方式启动,无需安装 Node 与依赖。详见 [project-md/deploy.md](project-md/deploy.md)。

启动后:
1. 设置主密码(首次)→ 进入;之后每次启动输入主密码解锁
2. "服务器"页:新增服务器(alias/host/port/user/auth + 密码或私钥)→ 测试/cmd
3. "设置 → 命令策略/路径策略":查看默认策略,按需新增自定义策略
4. "项目"页:新增项目(绑定服务器 + 部署路径 + 选择命令/路径策略)
5. "服务"页:启动服务 → 复制 URL + Token(及 Claude/OpenCode 配置)
6. 把配置粘贴到开发工具,即可使用

## 提供的 MCP 工具

`list_servers` / `list_projects` / `list_policies` / `list_tools` / `request_command` / `list_approval_requests` / `ssh_exec` / `sftp_list` / `sftp_stat` / `sftp_read` / `sftp_write` / `sftp_mkdir` / `sftp_delete` / `sftp_upload` / `sftp_download` / `deploy_project`

- `deploy_project` 以**项目名 `project`** 引用,自动解析绑定的服务器 + 该项目 deployPath + 该项目绑定的命令/路径策略;
- `ssh_exec`/`sftp_*` 以服务器 `alias` 引用,使用**默认策略**;
- `list_servers` 只返回元数据(不含密码/私钥);凭证在服务端内部解析,从不回传。

## 安全模型

- **凭证隔离**:所有服务器**连接信息**(含账号/密码/私钥)整体加密存于 `data/credentials.enc`;`list_servers` 只返回元数据;主密码全局、仅人工在 Electron 界面输入后存于内存、不落盘、不进任何客户端配置。开发工具/LLM 即便有宿主文件读取能力,磁盘上也无明文主密码可解密。策略不含密钥,明文存于 `config.json`。
- **HTTP 鉴权**:仅 `127.0.0.1`、Bearer Token(启动随机生成、由人工复制给开发工具)。
- **命令策略**:黑名单(默认)/白名单,对完整命令串与各分段(按 `| ; && ||`)匹配,在全局危险命令黑名单之上叠加策略 `denyPatterns`;拦截 `passwd`/`rm -rf /`/`mkfs`/`shutdown`/fork bomb/写 `authorized_keys` 等。`allowExec`/`allowWrite` 开关也在策略上。
- **路径策略**:归一化后限定在项目 `deployPath` + 策略 `allowedPaths`;全局禁用 `/`、`/etc`、`/root` 等;禁止删除根;防 `../` 遍历。
- **策略绑定不可破坏**:项目按策略**不可变 id** 绑定;改策略名/内容不影响已绑定项目;默认策略不可删。
- **审批模式**:命令策略 approval 模式下,白名单放行、黑名单拦截、其余命令需人工在界面审批后进临时白名单;LLM 可调 `request_command` 申请。
- **全局禁止 `mkdir`/`touch`**:目录/文件新建只能走 SFTP 工具,shell 不允许新建。
- **默认 allowlist 预置**:docker/docker-compose/kubectl 等容器与 k8s 命令、以及只读诊断命令(ls/cat/grep/journalctl 等)默认放行。
- **命令日志**:`data/audit.log`(保留 3 个月滚动清除),界面可查看与清空,含项目名称字段,支持按结果过滤与分页浏览。

## 项目结构

```
src/                          MCP 核心(TS, ESM)
  http.ts                     Streamable HTTP 服务 + Bearer Token + 端口 54110
  tools/                      13 个 MCP 工具
  security/                   commandPolicy / pathPolicy / audit / sanitizer
  connection/                 SSH/SFTP 连接管理(ssh2)
  config/                     config.json(项目+策略+设置) + AES 凭证存储(credentials.enc 存服务器连接信息)
  utils/
electron/
  main/index.ts               主进程:窗口 + IPC + 启停服务 + 解锁 + 策略 IPC
  preload/index.ts            安全 IPC 桥(CJS)
  renderer/                   React UI(解锁门/服务器/项目/服务/命令日志/设置[策略])
data/                         运行时生成(配置/凭证/审计),gitignore
```

## 文档索引

- [AGENTS.md](AGENTS.md) — 给 AI 代理/开发者的代码贡献指引与分层不变量
- [project-md/deploy.md](project-md/deploy.md) — 构建与部署、客户端注册、安全加固
- [project-md/guide.md](project-md/guide.md) — 使用指南:界面操作、HTTP 工具调用、工作流

## Windows 安装包打包

```bash
npm run dist:win      # = electron-vite build && electron-builder --win nsis
```

产物(均 gitignore,不入库):`release/mcp-ssh-<version>-setup.exe`(NSIS 安装包)。安装到用户目录(默认 `%LOCALAPPDATA%\Programs\mcp-ssh\`),从开始菜单/桌面「mcp-ssh」快捷方式启动,无需每次解压。数据目录指向 `app.getPath('userData')`(`%APPDATA%\mcp-ssh`,随安装持久、卸载不影响):`config.json` / `credentials.enc` / `audit.log`。

> **Windows Defender 提示**:`electron-builder --win nsis` 重新解压 electron 时,Defender 实时扫描可能锁住 `win-unpacked.tmp → win-unpacked` 的重命名 / `default_app.asar`,报 `EPERM`/`EBUSY`。可加 Defender 排除,或手动组装 `release/win-unpacked/` 后用 `--prepackaged` 跳过解压步骤(详见 [AGENTS.md](AGENTS.md))。

## 技术栈

TypeScript(ESM) · Electron · React + Vite(electron-vite) · `@modelcontextprotocol/sdk` · `ssh2` · `zod` · `vitest`

## License

MIT