# ssh-mcp-server

**Repository Path**: laoliu97/ssh-mcp-server

## Basic Information

- **Project Name**: ssh-mcp-server
- **Description**: 一个专注于SSH多连接管理的开源服务器项目，支持高效安全的远程操作与管理，适用于多种网络环境。把 Claude / AI 助手变成远程运维专家 — 21 工具 SSH MCP 服务器，含完整交互式终端、安全护栏、长任务取消
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-05-10
- **Last Updated**: 2026-05-11

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# ssh-mcp-server

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](./LICENSE)
[![Go](https://img.shields.io/badge/Go-1.24%2B-00ADD8.svg)](https://go.dev/)

把 Claude / AI 助手变成远程运维专家 —— 一个真正能用的 SSH MCP 服务器，提供 21 个工具、完整交互式终端、安全护栏与 LLM 友好返回。

```
协议   MCP over stdio (JSON-RPC 2.0)
工具   21 个：连接 / 执行 / shell / SFTP / 历史 / 任务管理
终端   ECMA-48 ANSI 过滤 + VT10x 模拟（vim / top / htop 可用）
保活   TCP (30s) + SSH (30s) + 应用心跳 (60s)
缓冲   10000 行环形缓冲，异步执行不丢数据
平台   Windows · Linux · macOS × amd64 / arm64 / arm / 386
```

## 特点

- **21 个细粒度工具** — 连接 / 执行 / 交互式 shell / SFTP / 主机管理 / 历史 / 任务取消，覆盖完整运维场景
- **真正的交互式终端** — 不是简单的命令执行，而是带 PTY 的完整 shell，能跑 vim、top、htop、vi、less
- **异步模式（2ms 启动）** — Shell 起来立刻返回，命令在后台跑，10000 行环形缓冲不丢数据
- **三层保活** — TCP keepalive + SSH keepalive + 应用心跳，长会话不掉线
- **ECMA-48 标准 ANSI 过滤** — 不用 stripansi，从根上解决 OSC 序列丢字符问题
- **会话别名系统** — `ssh_connect alias=prod-db`，告别记 UUID
- **完整命令历史** — 含交互 shell 中键入的命令
- **结构化错误码** — `[ERR_AUTH]` / `[ERR_NEEDS_CONFIRMATION]` 等 11 类前缀，LLM 直接分流
- **危险命令拦截** — `rm -rf /`、`mkfs`、`shutdown`、`dd of=/dev/sd*` 等 12 类默认拦截，需 LLM 显式确认
- **SSH host key 校验** — `strict / tofu / off` 三模式，默认 TOFU，自动写入 known_hosts
- **密码间接引用** — `password_env` / `password_cmd`，避免明文落 yaml
- **长任务取消** — 支持 `ssh_list_tasks` + `ssh_cancel`，长命令可中途停
- **输出风格开关** — `minimal` 模式去 emoji 节省 token，`verbose` 保留装饰
- **sudo 自动注入** — 配置 `sudo_password` 后无需再手动输入

## 快速开始

### 1. 下载 / 编译

```bash
# 自行编译（需 Go 1.24+）
git clone https://gitee.com/laoliu97/ssh-mcp-server.git
cd ssh-mcp-server
go build -o sshmcp ./cmd/server
```

跨平台一键打包：

```bash
# Linux / macOS
./build.sh

# Windows
.\build.ps1
```

### 2. 配置 Claude Desktop

编辑 `claude_desktop_config.json`（路径见 Anthropic 官方文档）：

```json
{
  "mcpServers": {
    "ssh-mcp-server": {
      "command": "C:\\path\\to\\sshmcp.exe"
    }
  }
}
```

### 3. 配置预定义主机（可选）

`~/.sshmcp.yaml` 或项目目录 `.sshmcp.yaml`：

```yaml
ssh:
  default_timeout: 30s
  host_key_check: tofu          # strict / tofu / off
  known_hosts_path: ""          # 空表示 ~/.ssh/known_hosts

output:
  style: minimal                # minimal / verbose

safety:
  enabled: true
  require_confirm_recursive_delete: true

hosts:
  - hostname: prod-db
    address: 10.0.0.1
    port: 22
    username: deploy
    password_env: PROD_DB_PASS  # 推荐：从环境变量读取
    private_key_path: ""

logging:
  level: info
  output: stderr                # 必须 stderr（stdout 是 MCP 协议通道）
```

### 4. 在 Claude 中使用

```
你：用 ssh_connect 连一下 prod-db
Claude: [调用 ssh_connect hostname=prod-db]
        Connected  id=abc-123  alias=prod-db

你：起个交互 shell，看看 /var/log/nginx 目录
Claude: [调用 ssh_shell session_id=abc-123]
        Shell ready  id=abc-123  mode=raw  size=120x40
        [调用 ssh_exec_in_shell command="ls /var/log/nginx"]
        access.log  error.log
```

## 在 Android / Termux 上运行

Termux 是 Android 上的 Linux 用户态环境，能直接跑 `linux-arm64` / `linux-arm` 二进制。本项目提供了 `android-arm64` `android-arm` 两个目标，命名清晰但**实质就是 Linux ARM 二进制**（Go 原生 `GOOS=android` 需要 Android NDK + CGO，与本项目静态编译策略冲突，故走 Termux 兼容方案）。

### 1. 安装 Termux

从 [F-Droid](https://f-droid.org/packages/com.termux/) 安装（Google Play 版本已停止维护）。

### 2. 在 Termux 中获取二进制

**方案 A：用源码自行编译（推荐，最干净）**

```bash
# Termux 里安装 Go + git
pkg update && pkg install -y golang git

# 拉源码 + 编译
git clone https://gitee.com/laoliu97/ssh-mcp-server.git
cd ssh-mcp-server
go build -o sshmcp ./cmd/server

# 安装到 PATH
mkdir -p ~/bin && mv sshmcp ~/bin/
```

**方案 B：在 PC 交叉编译后上传**

PC 上编译后 `scp` 或 `adb push` 到设备：

```bash
# PC 端
.\build.ps1                   # Windows
./build.sh                    # Linux/macOS
# 产出 build/sshmcp-android-arm64

# 通过 Termux 内置 sshd 上传，或 adb push
adb push build/sshmcp-android-arm64 /data/local/tmp/sshmcp
# Termux 里:
mv /data/local/tmp/sshmcp ~/bin/sshmcp && chmod +x ~/bin/sshmcp
```

### 3. 适用场景

Android/Termux 上的典型用法：

- **Termux 跑 Claude Code（CLI 版）**：`pkg install nodejs` 后 `npm install -g @anthropic-ai/claude-code`，用 sshmcp 作为 MCP server，让 AI 通过手机管理服务器
- **作为 sshd 跳板**：手机做出口，桌面端 SSH 到手机，再通过 sshmcp 操作其他机器
- **本地开发测试**：在手机/平板上验证 MCP 协议交互

### 4. Termux 注意事项

- **架构**：现代 Android 基本都是 `arm64`（aarch64），用 `android-arm64`；老 32 位 ARM 设备用 `android-arm`
- **运行时检查**：在 Termux 里跑 `uname -m` 看架构（`aarch64` → arm64，`armv7l/armv8l` → arm）
- **后台保活**：Termux 后台容易被系统杀，用 `termux-wake-lock` + `nohup sshmcp &` 长跑
- **存储权限**：用到 SFTP 上传到手机文件系统时跑一次 `termux-setup-storage`
- **配置文件位置**：`~/.sshmcp.yaml`，`logging.output: stderr` 必须保持

## 21 个工具一览

| 类别 | 工具 |
|------|------|
| **连接管理** | `ssh_connect` · `ssh_disconnect` · `ssh_list_sessions` · `ssh_session_info` |
| **命令执行** | `ssh_exec` · `ssh_exec_batch` |
| **交互式 Shell** | `ssh_shell` · `ssh_exec_in_shell` · `ssh_read_output` · `ssh_terminal_snapshot` · `ssh_shell_status` · `ssh_close_shell` |
| **SFTP** | `sftp_upload` · `sftp_download` · `sftp_list` · `sftp_delete` |
| **主机管理** | `ssh_save_host` · `ssh_list_hosts` · `ssh_remove_host` |
| **历史与任务** | `ssh_history` · `ssh_list_tasks` · `ssh_cancel` |

## 安全设计

### 危险命令拦截

默认拦截 12 类高危命令（可在 config 中配置正则）：

```
rm -rf /         mkfs /dev/*       shutdown / halt / reboot
:(){:|:&};:      dd of=/dev/sd*    chmod -R 777 /
> /dev/sda*      crontab -r        userdel -r
DROP DATABASE    TRUNCATE TABLE    rm -rf 内核或系统目录
```

命中后返回 `[ERR_NEEDS_CONFIRMATION]`，LLM 必须把命令完整告知用户、获得显式同意后以 `confirmed=true` 重发才会执行。

### Host key 校验

```yaml
ssh:
  host_key_check: tofu   # 默认：首次连接自动写 known_hosts，变化拒绝
  # strict — 必须事先在 known_hosts；不在则拒绝
  # off    — 跳过校验（不安全，仅测试用）
```

### 密码不落明文

```yaml
hosts:
  - hostname: prod
    password_env: PROD_PASS        # 从 $PROD_PASS 读
    password_cmd: "security find-generic-password -w -s prod"  # 或外部命令
    # password: xxx                # 不推荐，启动会打印 WARN
```

## 错误码速查

| 前缀 | 含义 |
|------|------|
| `[ERR_AUTH]` | SSH 认证失败 |
| `[ERR_NETWORK]` | 网络/超时/不可达 |
| `[ERR_NOT_FOUND]` | 会话/主机/文件不存在 |
| `[ERR_PERMISSION]` | 权限不足 |
| `[ERR_INVALID_ARG]` | 参数错误 |
| `[ERR_NO_SHELL]` | 会话未启动 shell |
| `[ERR_NEEDS_CONFIRMATION]` | 危险命令需二次确认 |
| `[ERR_HOST_KEY_MISMATCH]` | host key 与 known_hosts 不一致 |
| `[ERR_ALREADY_EXIST]` | 资源冲突 |
| `[ERR_UNSUPPORTED]` | 功能未启用 |
| `[ERR_INTERNAL]` | 服务端内部错误 |

## 限制

- **不是 SSH 客户端工具**：定位是给 LLM 用的 MCP 服务器，不替代 PuTTY / OpenSSH
- **stdio 协议**：日志必须输出到 stderr（默认配置已正确，请勿改 `logging.output: stdout`）
- **SFTP 大文件**：当前实现一次性传输，超大文件请走原生 scp/rsync
- **shell working_dir**：通过 `cd` 命令进入，依赖远端 prompt 解析；自定义 PS1 可能导致目录检测延迟（带 2s 超时兜底）

## 配置完整示例

参见 [config.example.yaml](config.example.yaml)。

## 详细使用文档

参见 [MCP使用说明.md](MCP使用说明.md)。

## 许可证

MIT License — 详见 [LICENSE](LICENSE)。