STARWARCLOUD STARWAR.AI
返回市场
ssh-mcp服务器

ssh-mcp服务器

作者：classfang89 星标更新：2025-11-21
安装使用来源：spider==github.com

项目介绍

技术文档摘要

🔐 ssh-mcp-server

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

英文文档 | 中文文档

📝 项目概述

ssh-mcp-server 是一个桥接工具，使支持MCP协议的AI助手和其他应用程序能够通过标准化接口执行远程SSH命令。这使得AI助手能够在不直接暴露SSH凭证的情况下安全地操作远程服务器、执行命令并获取结果。

✨ 主要特性

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

📦 开源仓库

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

NPM: https://www.npmjs.com/package/@fangjunjie/ssh-mcp-server

🛠️ 工具列表

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

📚 使用方法

🔧 MCP配置示例

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

⚙️ 命令行选项

选项:
  -h, --host          SSH服务器主机地址
  -p, --port          SSH服务器端口
  -u, --username      SSH用户名
  -w, --password      SSH密码
  -k, --privateKey    SSH私钥文件路径
  -P, --passphrase    私钥密码短语（如果有）
  -W, --whitelist     命令白名单，逗号分隔的正则表达式
  -B, --blacklist     命令黑名单，逗号分隔的正则表达式
  -s, --socksProxy    SOCKS代理服务器地址（如，socks://user:password@host:port）

🔑 使用密码

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

🔐 使用私钥

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

🔏 使用带有密码短语的私钥

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

🌐 使用SOCKS代理

{
  "mcpServers": {
    "ssh-mpc-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参数来限制可执行命令的范围。多个模式之间用逗号分隔。每个模式都是用于匹配命令的正则表达式。

示例：使用命令白名单

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

示例：使用命令黑名单

{
  "mcpServers": {
    "ssh-mpc-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参数来指定多个SSH连接，每个参数都有一个唯一的名称：

npx @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"

在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工具支持超时选项以防止命令无限期挂起：

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

这对于像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" }
]

🛡️ 安全注意事项

此服务器提供了强大的能力来执行命令和传输文件到远程服务器。为了确保其安全使用，请考虑以下几点：

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

🌟 星标历史

星标历史图表