npm package: @htmitech/mcp-ssh-executor
Description: MCP server for SSH connection and command execution with encrypted password support
Latest version: 1.0.0

# MCP SSH Executor

一个用于SSH连接和命令执行的MCP (Model Context Protocol) 服务器。支持密码加密存储、sudo自动密码输入、异步命令执行等功能。

## 功能特性

- 🔐 **密码加密存储**: 使用 AES-256-GCM 加密算法安全存储密码
- 🔑 **Sudo自动输入**: 自动检测sudo命令并输入密码
- ⚡ **异步命令执行**: 支持长时间运行命令的异步执行和状态跟踪
- 🔄 **多连接管理**: 同时管理多个SSH连接
- 📊 **任务管理**: 完整的任务状态跟踪和输出管理

## 安装

### 方式1：从 npm 安装（推荐）

```bash
npm install -g @your-npm-username/mcp-ssh-executor
```

### 方式2：从源码安装

```bash
git clone https://github.com/your-username/mcp-ssh-executor.git
cd mcp-ssh-executor
npm install
npm run build
```

## 配置

### 1. 生成主密钥

```bash
# 使用命令行工具生成主密钥
npm run encrypt-password generate-key
```

将生成的主密钥设置为环境变量：

```powershell
# Windows PowerShell
$env:MCP_SSH_MASTER_KEY = "你的主密钥"

# 或者添加到系统环境变量
[Environment]::SetEnvironmentVariable("MCP_SSH_MASTER_KEY", "你的主密钥", "User")
```

```bash
# Linux/Mac
export MCP_SSH_MASTER_KEY="你的主密钥"

# 或添加到 ~/.bashrc 或 ~/.zshrc
echo 'export MCP_SSH_MASTER_KEY="你的主密钥"' >> ~/.bashrc
```

### 2. 加密密码

```bash
# 交互式加密密码
npm run encrypt-password

# 或者直接传入密码
npm run encrypt-password "your-password"
```

### 3. 创建配置文件

复制示例配置文件并修改：

```bash
cp servers.example.json servers.json
```

编辑 `servers.json`：

```json
{
  "servers": {
    "production": {
      "host": "192.168.1.100",
      "port": 22,
      "username": "root",
      "passwordEncrypted": "加密后的密码字符串"
    },
    "development": {
      "host": "dev.example.com",
      "port": 22,
      "username": "developer",
      "passwordEncrypted": "加密后的密码",
      "sudoPasswordEncrypted": "加密后的sudo密码"
    }
  },
  "masterKeyEnv": "MCP_SSH_MASTER_KEY"
}
```

## MCP 配置

在 Cursor 或其他 MCP 客户端中添加此服务器：

```json
{
  "mcpServers": {
    "ssh-executor": {
      "command": "node",
      "args": ["E:/mcp/dist/index.js"],
      "env": {
        "MCP_SSH_MASTER_KEY": "你的主密钥",
        "MCP_SSH_CONFIG_PATH": "E:/mcp/servers.json"
      }
    }
  }
}
```

## 可用工具

### 连接管理

| 工具 | 描述 |
|------|------|
| `ssh_connect` | 连接到SSH服务器 |
| `ssh_disconnect` | 断开SSH连接 |
| `ssh_list_connections` | 列出当前所有SSH连接 |
| `ssh_list_servers` | 列出配置文件中的所有服务器 |

### 命令执行

| 工具 | 描述 |
|------|------|
| `ssh_execute` | 同步执行命令（等待完成） |
| `ssh_execute_async` | 异步执行命令（立即返回任务ID） |

### 任务管理

| 工具 | 描述 |
|------|------|
| `ssh_task_status` | 获取异步任务状态 |
| `ssh_task_output` | 获取异步任务输出 |
| `ssh_task_cancel` | 取消正在运行的任务 |
| `ssh_list_tasks` | 列出所有任务 |

### 密钥管理

| 工具 | 描述 |
|------|------|
| `ssh_encrypt_password` | 加密密码 |
| `ssh_generate_master_key` | 生成新的主密钥 |

## 使用示例

### 基本命令执行

```
1. 连接服务器：ssh_connect(serverName: "production")
2. 执行命令：ssh_execute(connectionId: "production", command: "ls -la")
3. 断开连接：ssh_disconnect(connectionId: "production")
```

### Sudo 命令

```
ssh_execute(connectionId: "production", command: "sudo apt update")
# 会自动检测sudo提示并输入配置文件中的密码
```

### 异步执行长时间命令

```
1. 启动任务：ssh_execute_async(connectionId: "production", command: "apt upgrade -y")
   → 返回 taskId: "abc123"

2. 检查状态：ssh_task_status(taskId: "abc123")
   → 返回 { status: "running", ... }

3. 获取输出：ssh_task_output(taskId: "abc123", outputType: "stdout")
   → 返回当前输出内容

4. 取消任务（如需要）：ssh_task_cancel(taskId: "abc123")
```

## 安全注意事项

1. **主密钥保护**: 主密钥应该安全存储，不要提交到版本控制
2. **配置文件权限**: 确保 `servers.json` 文件权限适当限制
3. **避免明文密码**: 尽量使用 `passwordEncrypted` 而不是 `password`
4. **私钥认证**: 如果可能，优先使用SSH私钥认证

## 开发

```bash
# 开发模式运行
npm run dev

# 构建
npm run build

# 启动
npm start
```

## License

MIT