MCP SSH Executor

一个用于SSH连接和命令执行的MCP (Model Context Protocol) 服务器。支持密码加密存储、sudo自动密码输入、异步命令执行等功能。

功能特性

• 🔐 密码加密存储: 使用 AES-256-GCM 加密算法安全存储密码
• 🔑 Sudo自动输入: 自动检测sudo命令并输入密码
• ⚡ 异步命令执行: 支持长时间运行命令的异步执行和状态跟踪
• 🔄 多连接管理: 同时管理多个SSH连接
• 📊 任务管理: 完整的任务状态跟踪和输出管理

安装

方式1：从 npm 安装（推荐）

npm install -g @htmitech/mcp-ssh-executor

方式2：从源码安装

git clone https://github.com/your-username/mcp-ssh-executor.git
cd mcp-ssh-executor
npm install
npm run build

配置

1. 生成主密钥

# 使用命令行工具生成主密钥
npm run encrypt-password generate-key

将生成的主密钥设置为环境变量：

# Windows PowerShell
$env:MCP_SSH_MASTER_KEY = "你的主密钥"

# 或者添加到系统环境变量
[Environment]::SetEnvironmentVariable("MCP_SSH_MASTER_KEY", "你的主密钥", "User")

# Linux/Mac
export MCP_SSH_MASTER_KEY="你的主密钥"

# 或添加到 ~/.bashrc 或 ~/.zshrc
echo 'export MCP_SSH_MASTER_KEY="你的主密钥"' >> ~/.bashrc

2. 加密密码

# 交互式加密密码
npm run encrypt-password

# 或者直接传入密码
npm run encrypt-password "your-password"

3. 创建配置文件

复制示例配置文件并修改：

cp servers.example.json servers.json

编辑 servers.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 客户端中添加此服务器：

{
  "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_upload_file | 上传文件到远程服务器（支持本地路径或直接传入内容，最大10MB） |

任务管理

| 工具 | 描述 | |------|------| | 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：上传本地文件

ssh_upload_file(
  connectionId: "production",
  remotePath: "/home/user/docker-compose.yml",
  localPath: "C:/projects/myapp/docker-compose.yml"
)

方式2：直接传入文件内容（推荐用于AI生成的配置文件）

ssh_upload_file(
  connectionId: "production",
  remotePath: "/home/user/docker-compose.yml",
  content: "version: '3'\nservices:\n  web:\n    image: nginx:latest\n    ports:\n      - '80:80'"
)

支持的文件类型：

• Docker配置：docker-compose.yml、Dockerfile
• Shell脚本：*.sh
• 配置文件：nginx.conf、*.json、*.yaml 等
• 最大文件大小：10MB

安全注意事项

1. 主密钥保护: 主密钥应该安全存储，不要提交到版本控制
2. 配置文件权限: 确保 servers.json 文件权限适当限制
3. 避免明文密码: 尽量使用 passwordEncrypted 而不是 password
4. 私钥认证: 如果可能，优先使用SSH私钥认证

开发

# 开发模式运行
npm run dev

# 构建
npm run build

# 启动
npm start

测试

使用 MCP Inspector 官方测试工具进行调试：

npx @modelcontextprotocol/inspector node dist/index.js

启动后会自动打开浏览器，访问 Web UI 界面进行测试。你可以：

• 查看所有可用工具
• 手动调用工具并查看返回结果
• 配置环境变量（如 MCP_SSH_MASTER_KEY）

License

MIT