🔐 ssh-mcp-server

Ein SSH-basierter MCP-Server (Model Context Protocol), der die Remote-Ausführung von SSH-Befehlen über das MCP-Protokoll ermöglicht.

Englische Dokumentation | 中文文档

📝 Projektübersicht

ssh-mcp-server ist ein Brücken-Tool, das es KI-Assistenten und anderen Anwendungen, die das MCP-Protokoll unterstützen, ermöglicht, Remote-SSH-Befehle über eine standardisierte Schnittstelle auszuführen. Dies erlaubt KI-Assistenten, sicher auf Remote-Server zuzugreifen, Befehle auszuführen und Ergebnisse abzurufen, ohne SSH-Anmeldeinformationen direkt an KI-Modelle preiszugeben.

Willkommen in unserer WeChat-Gruppe:

✨ Hauptfunktionen

• 🔒 Sichere Verbindungen: Unterstützt mehrere sichere SSH-Verbindungsmethoden, einschließlich Passwort-Authentifizierung und Authentifizierung mittels privatem Schlüssel (mit Unterstützung für Passphrasen)

• 🛡️ Befehlssicherheitskontrolle: Präzise Steuerung des Bereichs erlaubter Befehle durch flexible Blacklist- und Whitelist-Mechanismen, um gefährliche Operationen zu verhindern

• 🔄 Standardisierte Schnittstelle: Entspricht den MCP-Protokollspezifikationen für eine nahtlose Integration mit KI-Assistenten, die das Protokoll unterstützen

• 📂 Dateiübertragung: Unterstützt bidirektionale Dateiübertragungen, das Hochladen lokaler Dateien auf Server oder das Herunterladen von Dateien von Servern

• 🔑 Isolierung von Anmeldeinformationen: SSH-Anmeldeinformationen werden vollständig lokal verwaltet und niemals an KI-Modelle weitergegeben, was die Sicherheit erhöht

• 🚀 Sofort einsatzbereit: Kann direkt mit NPX ohne globale Installation ausgeführt werden, was die Bereitstellung bequem und schnell macht

📦 Open-Source-Repository

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

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

🛠️ Tool-Liste

📚 Verwendung

🔧 MCP-Konfigurationsbeispiele

⚠️ Wichtig: In MCP-Konfigurationsdateien muss jedes Befehlszeilenargument und sein Wert ein separates Element im args-Array sein. Kombinieren Sie diese NICHT mit Leerzeichen. Verwenden Sie zum Beispiel "--host", "192.168.1.1" anstelle von "--host 192.168.1.1".

⚙️ Befehlszeilenoptionen

Options:
  --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

🔑 Verwendung eines Passworts

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

🔐 Verwendung eines privaten Schlüssels

{
  "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"
      ]
    }
  }
}

🔏 Verwendung eines privaten Schlüssels mit Passphrase

{
  "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"
      ]
    }
  }
}

📋 Verwendung von ~/.ssh/config

Sie können Host-Aliase verwenden, die in Ihrer ~/.ssh/config-Datei definiert sind. Der Server liest die Verbindungsparameter automatisch aus der SSH-Konfiguration:

{
  "mcpServers": {
    "ssh-mcp-server": {
      "command": "npx",
      "args": [
        "-y",
        "@fangjunjie/ssh-mcp-server",
        "--host", "myserver"
      ]
    }
  }
}

Angenommen, Ihre ~/.ssh/config enthält:

Host myserver
    HostName 192.168.1.1
    Port 22
    User root
    IdentityFile ~/.ssh/id_rsa

Sie können auch einen benutzerdefinierten Pfad zur SSH-Konfigurationsdatei angeben:

{
  "mcpServers": {
    "ssh-mcp-server": {
      "command": "npx",
      "args": [
        "-y",
        "@fangjunjie/ssh-mcp-server",
        "--host", "myserver",
        "--ssh-config-file", "/path/to/custom/ssh_config"
      ]
    }
  }
}

Hinweis: Befehlszeilenparameter haben Vorrang vor Werten aus der SSH-Konfiguration. Wenn Sie beispielsweise --port 2222 angeben, überschreibt dies den Port aus der SSH-Konfiguration.

🌐 Verwendung eines SOCKS-Proxys

{
  "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"
      ]
    }
  }
}

📝 Verwendung von Befehls-Whitelist und -Blacklist

Verwenden Sie die Parameter --whitelist und --blacklist, um den Bereich der ausführbaren Befehle einzuschränken. Mehrere Muster werden durch Kommas getrennt. Jedes Muster ist ein regulärer Ausdruck, der zum Abgleich von Befehlen verwendet wird.

Beispiel: Verwendung einer Befehls-Whitelist

{
  "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.*"
      ]
    }
  }
}

Beispiel: Verwendung einer Befehls-Blacklist

{
  "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.*"
      ]
    }
  }
}

Hinweis: Wenn sowohl eine Whitelist als auch eine Blacklist angegeben sind, prüft das System zuerst, ob der Befehl in der Whitelist enthalten ist, und dann, ob er in der Blacklist steht. Der Befehl muss beide Prüfungen bestehen, um ausgeführt zu werden.

🧩 Beispiel für Multi-SSH-Verbindungen

Es gibt drei Möglichkeiten, mehrere SSH-Verbindungen zu konfigurieren:

📄 Methode 1: Verwendung einer Konfigurationsdatei (Empfohlen)

Erstellen Sie eine JSON-Konfigurationsdatei (z. B. ssh-config.json):

Array-Format:

[
  {
    "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"
  }
]

Objekt-Format:

{
  "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"
  }
}

Verwenden Sie dann den Parameter --config-file:

{
  "mcpServers": {
    "ssh-mcp-server": {
      "command": "npx",
      "args": [
        "-y",
        "@fangjunjie/ssh-mcp-server",
        "--config-file", "ssh-config.json"
      ]
    }
  }
}

🔧 Methode 2: Verwendung des JSON-Formats mit dem --ssh-Parameter

Sie können JSON-formatierte Konfigurationszeichenfolgen direkt übergeben:

{
  "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\"}"
      ]
    }
  }
}

📝 Methode 3: Legacy-Format mit Kommatrennung (Abwärtskompatibel)

Für einfache Fälle ohne Sonderzeichen in Passwörtern können Sie weiterhin das Legacy-Format verwenden:

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"

⚠️ Hinweis: Das Legacy-Format kann Probleme bei Passwörtern verursachen, die Sonderzeichen wie =, ,, {, } enthalten. Verwenden Sie Methode 1 oder Methode 2 für Passwörter mit Sonderzeichen.

Geben Sie in MCP-Tool-Aufrufen den Verbindungsnamen über den Parameter connectionName an. Wenn dieser weggelassen wird, wird die Standardverbindung verwendet.

Beispiel (Befehl auf der 'prod'-Verbindung ausführen):

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

Beispiel (Befehl mit Timeout-Optionen ausführen):

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

⏱️ Timeout bei der Befehlsausführung

Das execute-command-Tool unterstützt Timeout-Optionen, um zu verhindern, dass Befehle unendlich lange hängen bleiben:

• timeout: Timeout für die Befehlsausführung in Millisekunden (optional, Standardwert ist 30000ms)

• Fehlerantworten enthalten stabile code-, message- und retriable-Felder für eine einfachere Handhabung auf Agentenseite

Dies ist besonders nützlich für Befehle wie ping, tail -f oder andere lang laufende Prozesse, die die Ausführung blockieren könnten.

🗂️ Alle SSH-Server auflisten

Sie können das MCP-Tool list-servers verwenden, um alle verfügbaren SSH-Serverkonfigurationen abzurufen:

Beispielaufruf:

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

Beispielantwort:

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

🛡️ Sicherheitsüberlegungen

Dieser Server bietet leistungsstarke Funktionen zum Ausführen von Befehlen und Übertragen von Dateien auf Remote-Servern. Um eine sichere Verwendung zu gewährleisten, beachten Sie bitte Folgendes:

• Befehls-Whitelisting: Es wird dringend empfohlen, die Option --whitelist zu verwenden, um die Menge der ausführbaren Befehle einzuschränken. Ohne eine Whitelist kann jeder Befehl auf dem Remote-Server ausgeführt werden, was ein erhebliches Sicherheitsrisiko darstellen kann.

• Sicherheit privater Schlüssel: Der Server liest den privaten SSH-Schlüssel in den Arbeitsspeicher. Stellen Sie sicher, dass der Computer, auf dem der ssh-mcp-server läuft, sicher ist. Setzen Sie den Server keinen nicht vertrauenswürdigen Netzwerken aus.

• Denial of Service (DoS): Der Server verfügt über keine integrierte Ratenbegrenzung. Ein Angreifer könnte potenziell einen DoS-Angriff starten, indem er den Server mit Verbindungsanfragen oder großen Dateiübertragungen überflutet. Es wird empfohlen, den Server hinter einer Firewall oder einem Reverse-Proxy mit Ratenbegrenzungsfunktionen zu betreiben.

• Pfad-Traversal: Der Server verfügt über einen integrierten Schutz gegen Pfad-Traversal-Angriffe auf das lokale Dateisystem. Dennoch ist es wichtig, bei den in upload- und download-Befehlen verwendeten Pfaden vorsichtig zu sein.

• Lokaler Übertragungsumfang: Standardmäßig sind lokale Dateiübertragungen auf das aktuelle Arbeitsverzeichnis beschränkt. Verwenden Sie --allowed-local-paths oder allowedLocalPaths in der Konfiguration nur für explizit vertrauenswürdige Verzeichnisse.

🌟 Star History