# SSH MCP Server

基于 Model Context Protocol (MCP) 的 SSH 远程服务器管理工具，为 AI 代理提供标准化的 SSH 运维能力。使用 FastMCP + asyncssh 构建。

[English](README_EN.md)

## 特性

- **连接管理** — 懒连接、健康检查、自动重连、空闲超时
- **命令执行** — 远程命令、sudo（策略门控）、批量执行
- **文件操作** — SFTP 上传 / 下载 / 读写 / 删除 / 列表 / 元数据
- **部署运维** — 完整部署流程：上传 → 备份 → 放置 → 重启
- **安全设计** — 命令黑名单、路径限制、审计日志、确认门控、主机密钥验证
- **多服务器** — 单一配置文件管理多台服务器

## 快速开始

### 1. 安装

**方式一：下载预编译二进制（推荐）**

前往 [Releases](../../releases) 下载对应平台的可执行文件：

| 平台 | 文件 |
|------|------|
| macOS Apple Silicon | `open-ssh-mcp-darwin-arm64` |
| macOS Intel | `open-ssh-mcp-darwin-amd64` |
| Linux x86_64 | `open-ssh-mcp-linux-amd64` |
| Linux ARM64 | `open-ssh-mcp-linux-arm64` |
| Windows x64 | `open-ssh-mcp-windows-amd64.exe` |

下载后赋予执行权限：

```bash
chmod +x open-ssh-mcp-darwin-arm64
```

**方式二：从源码安装**

```bash
pip install -e .
```

### 2. 配置

复制示例配置并编辑：

```bash
cp config.example.json config.json
```

完整配置说明见 [配置说明](#配置说明)。

### 3. 在 Qoder 中配置

打开 Qoder → **Settings** → **MCP Servers**，添加以下配置：

**使用预编译二进制（推荐）：**

```json
{
  "mcpServers": {
    "ssh": {
      "command": "/path/to/open-ssh-mcp-darwin-arm64",
      "args": ["--config", "/path/to/config.json"]
    }
  }
}
```

**使用 uv 运行（开发模式）：**

```json
{
  "mcpServers": {
    "ssh": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/open-ssh-mcp", "ssh-mcp-server"],
      "env": {
        "SSH_MCP_CONFIG": "/path/to/config.json"
      }
    }
  }
}
```

> 将 `/path/to/` 替换为实际路径。Windows 用户请使用 `.exe` 文件路径。

### 4. 在其他 MCP 客户端中配置

Claude Desktop、Cursor 等客户端配置方式类似，在对应的 MCP 配置文件中添加上述 JSON 即可。

## 配置说明

配置为 JSON 格式，加载优先级：`--config` 参数 → `SSH_MCP_CONFIG` 环境变量 → 当前目录 `config.json`。

```json
{
  "defaults": {
    "port": 22,
    "username": "deploy",
    "auth_method": "key",
    "private_key_path": "~/.ssh/id_ed25519",
    "known_hosts": "~/.ssh/known_hosts",
    "connect_timeout_sec": 10,
    "command_timeout_sec": 30,
    "keepalive_interval_sec": 30,
    "keepalive_count_max": 3
  },
  "servers": {
    "web-prod-01": {
      "host": "10.0.1.11",
      "description": "生产 Web 服务器"
    }
  },
  "security": {
    "command_blocklist": ["rm -rf /", "mkfs", "shutdown", "reboot"],
    "blocked_paths": ["/etc/shadow", "/etc/sudoers"],
    "max_command_timeout_sec": 300,
    "audit_log_path": "~/.ssh-mcp/audit.jsonl",
    "require_confirmation_for": ["sudo", "systemctl restart", "rm"]
  },
  "pool": {
    "max_connections": 10,
    "idle_timeout_sec": 600,
    "health_check_interval_sec": 60,
    "auto_reconnect": true,
    "max_reconnect_attempts": 3
  }
}
```

设计要点：
- `defaults` 消除重复配置，每台服务器可覆盖任意字段
- `password_env` 引用环境变量名 — 配置文件中不存储明文密码
- 安全策略与服务器定义在同一文件中 — 单一配置源

## 可用工具

### 连接管理

| 工具 | 说明 |
|------|------|
| `ssh_connect` | 建立 SSH 连接 |
| `ssh_disconnect` | 断开连接 |
| `ssh_list_servers` | 列出所有已配置服务器及连接状态 |
| `ssh_status` | 检查连接健康状态：延迟、主机名、操作系统 |

### 命令执行

| 工具 | 说明 |
|------|------|
| `ssh_exec` | 执行远程命令 |
| `ssh_exec_sudo` | 以 sudo 执行（策略门控） |
| `ssh_exec_batch` | 顺序执行多条命令 |

### 文件操作

| 工具 | 说明 |
|------|------|
| `ssh_upload` | 上传本地文件到远程 |
| `ssh_download` | 下载远程文件 |
| `ssh_read_file` | 读取远程文件内容 |
| `ssh_write_file` | 写入 / 追加远程文件 |
| `ssh_delete_file` | 删除远程文件 / 目录 |
| `ssh_list_dir` | 列出目录内容 |
| `ssh_stat` | 获取文件元数据 |

### 部署运维

| 工具 | 说明 |
|------|------|
| `ssh_deploy` | 完整部署：上传 → 备份 → 放置 → 重启 |
| `ssh_restart_service` | 重启 systemd 服务 |
| `ssh_service_status` | 查看 systemd 服务状态 |
| `ssh_service_logs` | 获取近期服务日志 |

## 安全机制

- **命令黑名单** — 硬拒绝危险命令
- **路径限制** — 阻止访问敏感路径
- **Sudo 门控** — 特权操作需确认
- **审计日志** — 每次工具调用记录到 JSONL（时间戳、工具、服务器、命令、结果、耗时）
- **主机密钥验证** — 默认通过 `known_hosts` 启用

## 开发

```bash
# 安装开发依赖
pip install -e '.[dev]'

# 运行测试
pytest

# 代码检查
ruff check src/

# 本地打包（需要 PyInstaller）
pyinstaller --onefile --name open-ssh-mcp --paths src \
  --collect-all pydantic_core --collect-all cryptography \
  --collect-all asyncssh --collect-all mcp \
  build_entry.py
```

## 许可证

MIT