AI导哈

远程SSH命令执行工具

基于SSH和MCP协议的远程命令执行工具，支持安全连接、文件传输和批量操作，适用于AI助手远程服务器管理。

  • by ZachFlint
  • TypeScript
  • 本地部署
  • 更新于
在 GitHub 查看 ZachFlint/ssh-mcp-server

使用说明

ssh-mcp服务器

基于SSH的MCP（模型上下文协议）服务器，允许通过MCP协议远程执行SSH命令。

项目概述

ssh-mcp服务器是一个桥接工具，使AI助手和其他支持mcp协议的应用程序能够通过标准化接口执行远程ssh命令。这允许AI助手安全地操作远程服务器、执行命令和检索结果，而无需将SSH凭据直接暴露给AI模型。

主要特点

  • 安全连接：支持多种安全的SSH连接方法，包括密码身份验证和私钥身份验证（支持密码短语）
  • 指挥安全控制：通过灵活的黑名单和白名单机制精确控制允许的命令范围，防止危险操作
  • 标准化接口：符合MCP协议规范，可与支持该协议的AI助手无缝集成
  • 文件传输：支持双向文件传输，将本地文件上传到服务器或从服务器下载文件
  • 凭证隔离SSH凭据完全在本地管理，从不暴露于AI模型，增强了安全性
  • 准备使用：可以直接使用NPX运行，无需全局安装，部署方便快捷
  • 环境变量：通过环境变量支持凭据，以实现安全的CI/CD集成
  • 批量执行：使用单个工具调用按顺序执行多个命令

工具列表

工具 说明
execute命令 使用可选的cwd和sudo支持执行SSH命令
执行批处理 通过一次调用按顺序执行多个命令
读取文件 使用行范围支持从远程服务器读取文件内容
write-file 使用追加模式将内容写入远程服务器上的文件
上传 通过SFTP将本地文件上传到远程服务器
下载 通过SFTP从远程服务器下载文件
测试连接 测试SSH连接并返回服务器信息
获取状态 获取全面的系统状态（CPU、内存、磁盘、操作系统、进程）
检查端口 检查远程服务器上的端口是否打开/正在侦听
列出服务器 列出所有已配置的SSH连接

用法

MCP配置示例

重要：在MCP配置文件中，每个命令行参数及其值必须是 args 阵列。不要将它们与空格组合在一起。例如，使用 "--host", "192.168.1.1" 而不是 "--host 192.168.1.1".

命令行选项

Options:
  -h, --host          SSH server host address
  -p, --port          SSH server port
  -u, --username      SSH username
  -w, --password      SSH password
  -k, --privateKey    SSH private key file path
  -P, --passphrase    Private key passphrase (if any)
  -W, --whitelist     Command whitelist, comma-separated regular expressions
  -B, --blacklist     Command blacklist, comma-separated regular expressions
  -s, --socksProxy    SOCKS proxy server address (e.g., socks://user:password@host:port)
  -t, --timeout       Default command timeout in milliseconds (default: 30000)

Environment Variables (alternative to CLI options):
  SSH_HOST            SSH server host address
  SSH_PORT            SSH server port (default: 22)
  SSH_USERNAME        SSH username
  SSH_PASSWORD        SSH password
  SSH_PRIVATE_KEY     SSH private key file path
  SSH_PASSPHRASE      Private key passphrase
  SSH_WHITELIST       Command whitelist
  SSH_BLACKLIST       Command blacklist
  SSH_SOCKS_PROXY     SOCKS proxy server address
  SSH_TIMEOUT         Default command timeout in milliseconds

使用密码

{
  "mcpServers": {
    "ssh-mcp-server": {
      "command": "npx",
      "args": [
        "-y",
        "ssh-mcp-server",
        "--host", "192.168.1.1",
        "--port", "22",
        "--username", "root",
        "--password", "pwd123456"
      ]
    }
  }
}

使用私钥

{
  "mcpServers": {
    "ssh-mcp-server": {
      "command": "npx",
      "args": [
        "-y",
        "ssh-mcp-server",
        "--host", "192.168.1.1",
        "--port", "22",
        "--username", "root",
        "--privateKey", "~/.ssh/id_rsa"
      ]
    }
  }
}

使用私钥和密码短语

{
  "mcpServers": {
    "ssh-mcp-server": {
      "command": "npx",
      "args": [
        "-y",
        "ssh-mcp-server",
        "--host", "192.168.1.1",
        "--port", "22",
        "--username", "root",
        "--privateKey", "~/.ssh/id_rsa",
        "--passphrase", "pwd123456"
      ]
    }
  }
}

使用SOCKS代理

{
  "mcpServers": {
    "ssh-mcp-server": {
      "command": "npx",
      "args": [
        "-y",
        "ssh-mcp-server",
        "--host", "192.168.1.1",
        "--port", "22",
        "--username", "root",
        "--password", "pwd123456",
        "--socksProxy", "socks://username:password@proxy-host:proxy-port"
      ]
    }
  }
}

使用命令白名单和黑名单

使用 --whitelist 和 --blacklist 用于限制可执行命令范围的参数。多个模式用逗号分隔。每个模式都是一个用于匹配命令的正则表达式。

示例：使用命令白名单

{
  "mcpServers": {
    "ssh-mcp-server": {
      "command": "npx",
      "args": [
        "-y",
        "ssh-mcp-server",
        "--host", "192.168.1.1",
        "--port", "22",
        "--username", "root",
        "--password", "pwd123456",
        "--whitelist", "^ls( .*)?,^cat .*,^df.*"
      ]
    }
  }
}

示例：使用命令黑名单

{
  "mcpServers": {
    "ssh-mcp-server": {
      "command": "npx",
      "args": [
        "-y",
        "ssh-mcp-server",
        "--host", "192.168.1.1",
        "--port", "22",
        "--username", "root",
        "--password", "pwd123456",
        "--blacklist", "^rm .*,^shutdown.*,^reboot.*"
      ]
    }
  }
}

注意：如果同时指定了白名单和黑名单，系统将首先检查命令是否在白名单中，然后检查它是否在黑名单中。命令必须通过两个检查才能执行。

多SSH连接示例

您可以通过传递多个--SSH参数来指定多个SSH连接，每个参数都有一个唯一的名称：

npx ssh-mcp-server \
  --ssh "name=dev,host=1.2.3.4,port=22,user=alice,password=xxx" \
  --ssh "name=prod,host=5.6.7.8,port=22,user=bob,password=yyy"

在MCP工具调用中，通过指定连接名称 connectionName 参数。如果省略，则使用默认连接。

示例（在“prod”连接上执行命令）：

{
  "tool": "execute-command",
  "params": {
    "cmdString": "ls -al",
    "connectionName": "prod"
  }
}

示例（执行带有超时选项的命令）：

{
  "tool": "execute-command",
  "params": {
    "cmdString": "ping -c 10 127.0.0.1",
    "connectionName": "prod",
    "timeout": 5000
  }
}

命令执行超时

这 execute-command 该工具支持超时选项，以防止命令无限期挂起：

  • 超时：命令执行超时（毫秒）（可选，默认值为30000ms）

这对于以下命令特别有用 ping, tail -f，或可能阻止执行的其他长时间运行的进程。

列出所有SSH服务器

您可以使用MCP工具 list-servers 要获取所有可用的SSH服务器配置：

示例调用：

{
  "tool": "list-servers",
  "params": {}
}

示例响应：

[
  { "name": "dev", "host": "1.2.3.4", "port": 22, "username": "alice" },
  { "name": "prod", "host": "5.6.7.8", "port": 22, "username": "bob" }
]

测试连接

使用 test-connection 在运行命令之前验证SSH连接的工具：

{
  "tool": "test-connection",
  "params": {
    "connectionName": "prod"
  }
}

示例响应：

{
  "success": true,
  "connectionTime": "245ms",
  "server": {
    "host": "192.168.1.1",
    "port": 22,
    "username": "root",
    "hostname": "my-server"
  }
}

批处理命令执行

使用 execute-batch 按顺序运行多个命令的工具：

{
  "tool": "execute-batch",
  "params": {
    "commands": ["cd /var/log", "ls -la", "df -h"],
    "connectionName": "prod",
    "stopOnError": true
  }
}

示例响应：

{
  "summary": {
    "total": 3,
    "executed": 3,
    "succeeded": 3,
    "failed": 0
  },
  "results": [
    { "command": "cd /var/log", "success": true, "output": "", "executionTime": "12ms" },
    { "command": "ls -la", "success": true, "output": "...", "executionTime": "15ms" },
    { "command": "df -h", "success": true, "output": "...", "executionTime": "18ms" }
  ]
}

使用环境变量

对于CI/CD管道或安全部署，您可以使用环境变量而不是CLI参数：

{
  "mcpServers": {
    "ssh-mcp-server": {
      "command": "npx",
      "args": ["-y", "ssh-mcp-server"],
      "env": {
        "SSH_HOST": "192.168.1.1",
        "SSH_PORT": "22",
        "SSH_USERNAME": "root",
        "SSH_PASSWORD": "pwd123456"
      }
    }
  }
}

工作目录和Sudo

这 execute-command 工具支架 cwd 和 sudo 参数：

{
  "tool": "execute-command",
  "params": {
    "cmdString": "ls -la",
    "cwd": "/var/log",
    "sudo": true
  }
}

读取远程文件

使用可选行范围读取文件内容：

{
  "tool": "read-file",
  "params": {
    "path": "/etc/nginx/nginx.conf",
    "maxLines": 50,
    "startLine": 10
  }
}

写入远程文件

将内容写入远程文件：

{
  "tool": "write-file",
  "params": {
    "path": "/tmp/config.txt",
    "content": "key=value\nother=setting",
    "append": false,
    "createDirs": true
  }
}

获取服务器状态

获取全面的系统信息：

{
  "tool": "get-status",
  "params": {}
}

返回：主机名、操作系统、CPU、内存、磁盘、进程、服务、正常运行时间等。

检查端口

检查端口是否打开：

{
  "tool": "check-port",
  "params": {
    "port": 80,
    "host": "localhost"
  }
}

示例响应：

{
  "port": 80,
  "host": "localhost",
  "open": true,
  "service": "nginx",
  "pid": "1234"
}

安全考虑

此服务器提供了在远程服务器上执行命令和传输文件的强大功能。为确保安全使用，请考虑以下事项：

  • 命令白名单确实如此 强烈推荐 使用 --whitelist 选项来限制可以执行的命令集。如果没有白名单，任何命令都可以在远程服务器上执行，这可能是一个重大的安全风险。
  • 私钥安全：服务器将SSH私钥读入内存。确保机器运行 ssh-mcp-server 是安全的。不要将服务器暴露在不受信任的网络中。
  • 拒绝服务（DoS）：服务器没有内置速率限制。攻击者可能会通过向服务器发送大量连接请求或大文件传输来发起DoS攻击。建议在防火墙或具有速率限制功能的反向代理后运行服务器。
  • 路径遍历：服务器具有针对本地文件系统上的路径遍历攻击的内置保护。然而，仍然重要的是要注意在 upload 和 download 命令。

相关 MCP