⚙

SSH远程执行服务

基于SSH和MCP协议的远程命令执行和文件传输服务，为AI助手提供安全的服务器操作接口

作者 By classfang
本地部署 SSH协议 远程执行
GitHub

🔐 ssh-mcp服务器

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

英文文档| 中文文档

📝 项目概述

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

欢迎加入微信群：

✨ 主要特点

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

📦 开源存储库

github： https://github.com/classfang/ssh-mcp-server

NPM： https://www.npmjs.com/package/@方俊杰/ssh-mcp服务器

🛠️ 工具列表

工具名称描述
execute命令命令执行工具在远程服务器上执行SSH命令并获取结果
upload文件上传工具将本地文件上传到远程服务器上的指定位置
下载文件下载工具将文件从远程服务器下载到本地指定位置
列出服务器列出服务器工具列出所有可用的SSH服务器配置

📚 用法

🔧 MCP配置示例

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

⚙️ 命令行选项

TEXT``` 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16Options: —config-file JSON configuration file path (recommended for multiple servers) —ssh-config-file SSH config file path (default: ~/.ssh/config) —ssh SSH connection configuration (can be JSON string or legacy format) -h, —host SSH server host address or alias from SSH config -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) —allowed-local-paths Additional allowed local paths for upload/download, comma-separated —pty Allocate pseudo-tty for command execution (default: true) —pre-connect Pre-connect to all configured SSH servers on startup


#### 🔑 使用密码


JSON```
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15{
  "mcpServers": {
    "ssh-mcp-server": {
      "command": "npx",
      "args": [
        "-y",
        "@fangjunjie/ssh-mcp-server",
        "--host", "192.168.1.1",
        "--port", "22",
        "--username", "root",
        "--password", "pwd123456"
      ]
    }
  }
}

🔐 使用私钥

JSON``` 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15{ “mcpServers”: { “ssh-mcp-server”: { “command”: “npx”, “args”: [ “-y”, “@fangjunjie/ssh-mcp-server”, “—host”, “192.168.1.1”, “—port”, “22”, “—username”, “root”, “—privateKey”, ”~/.ssh/id_rsa” ] } } }


#### 🔏 使用私钥和密码短语


JSON```
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16{
  "mcpServers": {
    "ssh-mcp-server": {
      "command": "npx",
      "args": [
        "-y",
        "@fangjunjie/ssh-mcp-server",
        "--host", "192.168.1.1",
        "--port", "22",
        "--username", "root",
        "--privateKey", "~/.ssh/id_rsa",
        "--passphrase", "pwd123456"
      ]
    }
  }
}

📋 使用~/.ssh/config

您可以使用在您的 ~/.ssh/config 文件。服务器将自动从SSH配置中读取连接参数：

JSON``` 1 2 3 4 5 6 7 8 9 10 11 12{ “mcpServers”: { “ssh-mcp-server”: { “command”: “npx”, “args”: [ “-y”, “@fangjunjie/ssh-mcp-server”, “—host”, “myserver” ] } } }


假设你 `~/.ssh/config` 包含：

1 2 3 4 5Host myserver HostName 192.168.1.1 Port 22 User root IdentityFile ~/.ssh/id_rsa


您还可以指定自定义SSH配置文件路径：


JSON```
1
2
3
4
5
6
7
8
9
10
11
12
13{
  "mcpServers": {
    "ssh-mcp-server": {
      "command": "npx",
      "args": [
        "-y",
        "@fangjunjie/ssh-mcp-server",
        "--host", "myserver",
        "--ssh-config-file", "/path/to/custom/ssh_config"
      ]
    }
  }
}

备注：命令行参数优先于SSH配置值。例如，如果您指定 --port 2222，它将覆盖SSH配置中的端口。

🌐 使用SOCKS代理

JSON``` 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16{ “mcpServers”: { “ssh-mcp-server”: { “command”: “npx”, “args”: [ “-y”, “@fangjunjie/ssh-mcp-server”, “—host”, “192.168.1.1”, “—port”, “22”, “—username”, “root”, “—password”, “pwd123456”, “—socksProxy”, “socks://username:password@proxy-host:proxy-port” ] } } }


#### 📝 使用命令白名单和黑名单


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


示例：使用命令白名单


JSON```
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16{
  "mcpServers": {
    "ssh-mcp-server": {
      "command": "npx",
      "args": [
        "-y",
        "@fangjunjie/ssh-mcp-server",
        "--host", "192.168.1.1",
        "--port", "22",
        "--username", "root",
        "--password", "pwd123456",
        "--whitelist", "^ls( .*)?,^cat .*,^df.*"
      ]
    }
  }
}

示例：使用命令黑名单

JSON``` 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16{ “mcpServers”: { “ssh-mcp-server”: { “command”: “npx”, “args”: [ “-y”, “@fangjunjie/ssh-mcp-server”, “—host”, “192.168.1.1”, “—port”, “22”, “—username”, “root”, “—password”, “pwd123456”, “—blacklist”, “^rm .,^shutdown.,^reboot.*” ] } } }


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


### 🧩 多SSH连接示例


有三种方法可以配置多个SSH连接：


#### 📄 方法1：使用配置文件（推荐）


创建JSON配置文件（例如。， `ssh-config.json`):


**数组格式：**


JSON```
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18[
  {
    "name": "dev",
    "host": "1.2.3.4",
    "port": 22,
    "username": "alice",
    "password": "{abc=P100s0}",
    "socksProxy": "socks://127.0.0.1:10808"
  },
  {
    "name": "prod",
    "host": "5.6.7.8",
    "port": 22,
    "username": "bob",
    "password": "yyy",
    "socksProxy": "socks://127.0.0.1:10808"
  }
]

对象格式：

JSON``` 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16{ “dev”: { “host”: “1.2.3.4”, “port”: 22, “username”: “alice”, “password”: “{abc=P100s0}”, “socksProxy”: “socks://127.0.0.1:10808” }, “prod”: { “host”: “5.6.7.8”, “port”: 22, “username”: “bob”, “password”: “yyy”, “socksProxy”: “socks://127.0.0.1:10808” } }


然后使用 `--config-file` 参数：


JSON```
1
2
3
4
5
6
7
8
9
10
11
12{
  "mcpServers": {
    "ssh-mcp-server": {
      "command": "npx",
      "args": [
        "-y",
        "@fangjunjie/ssh-mcp-server",
        "--config-file", "ssh-config.json"
      ]
    }
  }
}

🔧 方法2：使用带有–ssh参数的JSON格式

您可以直接传递JSON格式的配置字符串：

JSON``` 1 2 3 4 5 6 7 8 9 10 11 12 13{ “mcpServers”: { “ssh-mcp-server”: { “command”: “npx”, “args”: [ “-y”, “@fangjunjie/ssh-mcp-server”, “—ssh”, ”{“name”:“dev”,“host”:“1.2.3.4”,“port”:22,“username”:“alice”,“password”:“{abc=P100s0}”,“socksProxy”:“socks://127.0.0.1:10808”}”, “—ssh”, ”{“name”:“prod”,“host”:“5.6.7.8”,“port”:22,“username”:“bob”,“password”:“yyy”,“socksProxy”:“socks://127.0.0.1:10808”}” ] } } }


#### 📝 方法3：传统逗号分隔格式（向后兼容）


对于密码中没有特殊字符的简单情况，您仍然可以使用传统格式：


BASH```
1
2
3npx @fangjunjie/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"

⚠️ 备注：传统格式可能存在包含特殊字符的密码问题，例如 =, ,, {, }对于带有特殊字符的密码，请使用方法1或方法2。

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

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

JSON``` 1 2 3 4 5 6 7{ “tool”: “execute-command”, “params”: { “cmdString”: “ls -al”, “connectionName”: “prod” } }


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


JSON```
1
2
3
4
5
6
7
8{
  "tool": "execute-command",
  "params": {
    "cmdString": "ping -c 10 127.0.0.1",
    "connectionName": "prod",
    "timeout": 5000
  }
}

⏱️ 命令执行超时

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

  • 超时：命令执行超时（毫秒）（可选，默认值为30000ms）
  • 错误响应包括稳定 code, message，以及 retriable 便于代理端处理的字段

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

🗂️ 列出所有SSH服务器

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

示例调用：

JSON``` 1 2 3 4{ “tool”: “list-servers”, “params”: {} }


示例响应：


JSON```
1
2
3
4[
  { "name": "dev", "host": "1.2.3.4", "port": 22, "username": "alice" },
  { "name": "prod", "host": "5.6.7.8", "port": 22, "username": "bob" }
]

🛡️ 安全考虑

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

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

🌟 星迹