mcp-ssh-tool

Ein Model Context Protocol (MCP) SSH-Client-Server, der autonome SSH-Operationen für GitHub Copilot und VS Code bereitstellt. Ermöglicht SSH-Automatisierung in natürlicher Sprache ohne manuelle Eingabeaufforderungen oder GUI-Interaktionen.

Offizieller MCP-Registry-Eintrag: io.github.oaslananka/mcp-ssh-tool
Registry-Metadaten: https://registry.modelcontextprotocol.io/v0.1/servers/io.github.oaslananka%2Fmcp-ssh-tool/versions/latest

Schnellstart

Installation

• Globale Installation (empfohlen): npm install -g mcp-ssh-tool

• Einmalige Ausführung: npx mcp-ssh-tool

MCP-Client-Konfiguration (VS Code / Claude Desktop / andere)

Fügen Sie dies zu Ihrer MCP-Konfiguration hinzu (mcp.json, .vscode/mcp.json oder die Claude Desktop MCP-Konfiguration):

{
  "servers": {
    "ssh-mcp": {
      "type": "stdio",
      "command": "mcp-ssh-tool",
      "args": []
    }
  }
}

Anwendungsbeispiele

Sobald die Konfiguration abgeschlossen ist, können Sie natürliche Sprache mit Ihrem MCP-Client verwenden:

• SSH-Verbindung: "Verbinde dich mit dem Server 192.168.1.100 als Admin unter Verwendung eines SSH-Schlüssels"

• Dateivorgänge: "Lies den Inhalt von /etc/nginx/nginx.conf auf dem Server"

• Befehlsausführung: "Führe 'systemctl status nginx' auf dem Remote-Server aus"

• Paketverwaltung: "Installiere das Paket htop auf dem Ubuntu-Server"

• Dienststeuerung: "Starte den Dienst nginx neu"

• Claude Desktop: "Verbinde dich mit meinem Server und prüfe die Festplattennutzung"

• Paket/Dienst-Stack installieren: "installiere nginx auf meinem Remote-Server"

• Konfigurationsdatei lesen: "lies die Datei /etc/nginx/nginx.conf"

• Dienst neu starten: "starte den Dienst nginx neu"

• Logs durchsuchen: "liste Dateien in /var/log auf"

Verfügbare Tools

• ssh_open_session - SSH-Verbindung mit verschiedenen Authentifizierungsmethoden herstellen

• ssh_close_session - SSH-Sitzung schließen

• ssh_list_sessions - Alle aktiven SSH-Sitzungen auflisten

• ssh_ping - Prüfen, ob eine Sitzung aktiv und reaktionsfähig ist

• ssh_list_configured_hosts - Hosts aus ~/.ssh/config auflisten

• ssh_resolve_host - Host-Alias aus der SSH-Konfiguration auflösen

• proc_exec - Befehle remote ausführen (mit optionalem Timeout)

• proc_sudo - Befehle mit Sudo-Rechten ausführen

• fs_read, fs_write, fs_list, fs_stat, fs_mkdirp, fs_rmrf, fs_rename - Dateisystemoperationen

• ensure_package - Paketverwaltung mit present (vorhanden) und absent (nicht vorhanden) Zuständen

• ensure_service - Dienststeuerung einschließlich restarted (neu gestartet)

• ensure_lines_in_file - Zeilenverwaltung in Dateien mit present und absent Zuständen

• patch_apply - Patches auf Dateien anwenden

• os_detect - Erkennung von Systeminformationen

• get_metrics - Server-Metriken im JSON- oder Prometheus-Format

• proc_exec_stream - Streaming-Befehlsausführung mit chunked Output

• file_upload, file_download - SFTP-Dateiübertragungs-Helfer

• tunnel_local_forward, tunnel_remote_forward, tunnel_close, tunnel_list - Tunnel-Verwaltung

Verfügbare Ressourcen

• mcp-ssh-tool://sessions/active - Aktive Sitzungen als JSON

• mcp-ssh-tool://metrics/json - Metriken-Snapshot als JSON

• mcp-ssh-tool://metrics/prometheus - Prometheus-Metriken-Export

• mcp-ssh-tool://ssh-config/hosts - Geparste lokale SSH-Host-Aliase

Übersicht

Der SSH-MCP-Server fungiert als Brücke zwischen GitHub Copilot und Remote-Systemen via SSH. Er unterstützt:

• Nicht-interaktive SSH-Operationen - Keine Eingabeaufforderungen oder GUI-Interaktionen

• Mehrere Authentifizierungsmethoden - Passwort, SSH-Schlüssel oder SSH-Agent

• Sitzungsverwaltung - Automatisches Verbindungspooling mit TTL und LRU-Eviction

• Dateisystemoperationen - Lesen, Schreiben, Auflisten und Verwalten von Remote-Dateien via SFTP, mit SSH-Shell-Fallbacks für Hosts, die kein SFTP-Subsystem bereitstellen

• Prozessausführung - Befehle und Sudo-Operationen remote ausführen

• High-Level-Automatisierung - Paketverwaltung, Dienststeuerung und Konfigurationsmanagement

• Sicherheit - Automatische Schwärzung sensibler Daten in Logs

Architektur

┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐
│  GitHub Copilot │────│  SSH MCP Server  │────│  Remote Systems │
│     / VS Code   │    │                  │    │   (via SSH)     │
└─────────────────┘    └──────────────────┘    └─────────────────┘
         │                       │                       │
         │ MCP stdio protocol    │ Session management    │ SSH + optional SFTP
         │                       │ LRU cache + TTL       │
         │                       │ Auth strategies       │

Eingebettete / BusyBox-Ziele

Einige eingebettete Ziele bieten SSH-Befehlsausführung, liefern aber kein SFTP-Subsystem mit, was bei Dropbear- oder BusyBox-basierten Systemen üblich ist. In diesem Fall ist ssh_open_session weiterhin erfolgreich und meldet sftpAvailable: false. Kern-Dateitools wie fs_read, fs_write, fs_stat, fs_list, fs_mkdirp, fs_rmrf und fs_rename greifen automatisch auf Shell-basierte Implementierungen zurück.

Installation

Voraussetzungen

• Node.js ≥ 20 (LTS)

• SSH-Zugriff auf Zielsysteme

• SSH-Schlüssel oder Anmeldedaten für die Authentifizierung

Installation via npm

npm install -g mcp-ssh-tool

Build aus dem Quellcode

git clone https://github.com/oaslananka/mcp-ssh-tool.git
cd mcp-ssh-tool
npm install
npm run build
npm link

CLI-Flags

• --help / -h: Nutzung und Beispiele anzeigen.

• --version / -v: Version ausgeben.

• --stdio: Stdio-Modus erzwingen (Standard).

Hinweis: Dies ist ein MCP-Stdio-Server. Das Terminal ist keine interaktive Shell; verwenden Sie einen MCP-Client (Claude Desktop, VS Code MCP, etc.) oder senden Sie JSON-RPC über Stdio.

Plattform-Hinweise

• Linux / macOS: Verwendet POSIX-Shell-Wrapper mit sicherem Quoting. Standard-Temp-Verzeichnis: /tmp.

• Windows-Ziele: Erfordert OpenSSH-Server/Agent; die Schlüsselsuche prüft C:\Users\<you>\.ssh\. Befehle werden für eine PowerShell-sichere Ausführung gewrappt. Paket-/Dienst-Helfer sind auf Windows-Zielen absichtlich deaktiviert.

• Host-Schlüssel: Die Host-Schlüssel-Prüfung ist standardmäßig gelockert. Setzen Sie STRICT_HOST_KEY_CHECKING=true und optional KNOWN_HOSTS_PATH, um die Verifizierung zu erzwingen.

ChatGPT Desktop-Integration

Schnelleinrichtung

npm run setup:chatgpt

Dieser Befehl konfiguriert ChatGPT Desktop automatisch für die Verwendung von mcp-ssh-tool.

Manuelle Einrichtung

Fügen Sie dies zu Ihrer ChatGPT Desktop MCP-Konfiguration hinzu:

• macOS: ~/Library/Application Support/ChatGPT/mcp.json

• Windows: %APPDATA%\ChatGPT\mcp.json

• Linux: ~/.config/chatgpt/mcp.json

{
  "mcpServers": {
    "ssh-mcp-server": {
      "name": "ssh-mcp-server",
      "command": "npx",
      "args": ["-y", "mcp-ssh-tool"]
    }
  }
}

Für eine detaillierte Nutzung siehe docs/chatgpt-usage.md.

Codex-Integration

Schnelleinrichtung

Installieren Sie das Paket global und registrieren Sie es dann bei Codex:

npm install -g mcp-ssh-tool
codex mcp add ssh-mcp -- mcp-ssh-tool

Wenn Sie es nicht global installieren möchten, können Sie es über npx registrieren:

codex mcp add ssh-mcp -- npx -y mcp-ssh-tool

Überprüfung

Prüfen Sie, ob Codex den MCP-Server sehen kann:

codex mcp list
codex mcp get ssh-mcp

Sie sollten einen aktivierten Stdio-Server sehen, dessen Befehl mcp-ssh-tool oder npx lautet.

Optionale Sicherheitsverschärfung

Um die Host-Schlüssel-Verifizierung im Codex-verwalteten Serverprozess zu erzwingen:

codex mcp remove ssh-mcp
codex mcp add ssh-mcp \
  --env STRICT_HOST_KEY_CHECKING=true \
  --env KNOWN_HOSTS_PATH=/path/to/known_hosts \
  -- mcp-ssh-tool

Starten Sie nach dem Hinzufügen des Servers Codex neu oder öffnen Sie eine neue Sitzung und versuchen Sie dann einen einfachen Tool-Aufruf, wie das Auflisten aktiver Sitzungen oder das Öffnen einer SSH-Verbindung.

VS Code Copilot-Integration

Konfiguration auf Benutzerebene (Empfohlen)

Öffnen Sie VS Code und drücken Sie Strg+Umschalt+P, führen Sie dann "MCP: Open User Configuration" aus.

Fügen Sie dies zu Ihrer mcp.json hinzu:

{
  "servers": {
    "ssh-mcp": {
      "type": "stdio",
      "command": "mcp-ssh-tool",
      "args": []
    }
  }
}

Konfiguration auf Workspace-Ebene

Erstellen Sie .vscode/mcp.json in Ihrem Workspace:

{
  "servers": {
    "ssh-mcp": {
      "type": "stdio",
      "command": "mcp-ssh-tool",
      "args": []
    }
  }
}

Überprüfung

1. Starten Sie VS Code neu

2. Öffnen Sie Copilot Chat

3. Die SSH-MCP-Tools sollten in der Liste der verfügbaren Tools erscheinen

4. Testen Sie mit: "Verbinde dich mit 192.168.1.100 als Admin und führe 'uname -a' aus"

Claude Desktop, Antigravity und andere MCP-Clients

Jeder MCP-kompatible Client, der einen Stdio-Server starten kann, kann mcp-ssh-tool verwenden. Der genaue Einstellungsbildschirm oder die Konfigurationsdatei variiert je nach Client, aber der Prozess ist derselbe:

1. Installieren Sie das Paket:

npm install -g mcp-ssh-tool

2. Registrieren Sie einen Stdio-MCP-Server, der Folgendes startet:

{
  "servers": {
    "ssh-mcp": {
      "type": "stdio",
      "command": "mcp-ssh-tool",
      "args": []
    }
  }
}

3. Wenn der Client ein mcpServers-Schema anstelle von servers verwendet, verwenden Sie den entsprechenden Eintrag:

{
  "mcpServers": {
    "ssh-mcp-server": {
      "command": "npx",
      "args": ["-y", "mcp-ssh-tool"]
    }
  }
}

Verwenden Sie für Claude Desktop dasselbe Stdio-Befehlsmuster wie oben in der MCP-Konfiguration. Verwenden Sie für Antigravity oder andere MCP-Clients die eigene MCP-Einstellungsoberfläche oder das Konfigurationsformat des Clients, verweisen Sie jedoch auf denselben ausführbaren Befehl.

Anwendungsbeispiele

Grundlegende Verbindung und Befehlsausführung

"Connect to 10.11.12.13 as deployer with password 'mypass' and run 'df -h'"

Dateivorgänge

"Connect to server.example.com as admin, read /etc/nginx/nginx.conf and show me the server blocks"

Systemadministration

"Connect to 192.168.1.50 as root, install htop package, start nginx service, and list /var/www contents"

Konfigurationsmanagement

"Connect to web-server as admin, add these lines to /etc/hosts:
192.168.1.10 db-server
192.168.1.20 cache-server
Then restart networking service"

Sofort einsatzbereite Prompt-Ideen

"connect to my server and check disk usage"

"install nginx on my remote server"

"read the file /etc/nginx/nginx.conf"

"restart the nginx service"

"list files in /var/log"

Profi-Tipps

• Mehrere Sitzungen: Öffnen Sie eine Sitzung pro Host oder Umgebung und halten Sie diese mit ssh_list_sessions und ssh_ping am Leben, wenn Sie zwischen Produktions-, Staging- und Entwicklungssystemen wechseln.

• SFTP-Fallback für BusyBox/Dropbear: Auf eingebetteten Systemen, die kein SFTP-Subsystem bereitstellen, kann ssh_open_session weiterhin mit sftpAvailable: false erfolgreich sein, und die Kern-fs_*-Tools greifen automatisch auf Shell-basierte Implementierungen zurück.

• Host-Schlüssel-Verifizierung: Setzen Sie STRICT_HOST_KEY_CHECKING=true in der MCP-Server-Umgebung und optional KNOWN_HOSTS_PATH für eine strengere SSH-Verifizierung auf Produktionsebene.

API-Referenz

Architektur

src/
├── container.ts       - Dependency injection wiring
├── config.ts          - ConfigManager (env + programmatic overrides)
├── index.ts           - CLI entry point & graceful shutdown
├── mcp.ts             - MCP server (thin: delegates to ToolRegistry)
├── tools/
│   ├── registry.ts    - ToolRegistry (routes CallTool requests)
│   ├── types.ts       - ToolProvider interface
│   ├── session.provider.ts
│   ├── process.provider.ts
│   ├── fs.provider.ts
│   ├── ensure.provider.ts
│   ├── system.provider.ts
│   ├── transfer.provider.ts
│   └── tunnel.provider.ts
├── session.ts         - SessionManager (LRU cache + TTL)
├── resources.ts       - MCP resources for sessions, metrics, and SSH hosts
├── telemetry.ts       - Optional OpenTelemetry tracing
├── rate-limiter.ts    - Sliding window rate limiter
├── metrics.ts         - Prometheus-compatible metrics
├── safety.ts          - Command safety warnings (non-blocking)
└── ...                - fs-tools, process, ensure, detect, ...

Hinzufügen einer neuen Tool-Gruppe

1. Erstellen Sie src/tools/<ihr-namespace>.provider.ts, das ToolProvider implementiert

2. Registrieren Sie es in src/tools/index.ts

3. Fügen Sie Unit-Tests zu test/unit/tools/<ihr-namespace>.provider.test.ts hinzu

Es sind keine Änderungen an mcp.ts erforderlich.

Sitzungs-Tools

ssh_open_session

{
  "host": "example.com",
  "username": "admin",
  "port": 22,
  "auth": "auto",
  "password": "optional",
  "privateKey": "optional-inline-key",
  "privateKeyPath": "optional-path",
  "passphrase": "optional",
  "useAgent": false,
  "readyTimeoutMs": 20000,
  "ttlMs": 900000
}

Gibt zurück:

{
  "sessionId": "ssh-1645123456789-1",
  "host": "example.com",
  "username": "admin",
  "expiresInMs": 900000
}

ssh_close_session

{
  "sessionId": "ssh-1645123456789-1"
}

ssh_list_sessions, ssh_ping, ssh_list_configured_hosts, ssh_resolve_host

• ssh_list_sessions gibt aktive Sitzungen mit verbleibender TTL zurück.

• ssh_ping prüft die Aktivität und Latenz einer Sitzung.

• ssh_list_configured_hosts liest ~/.ssh/config.

• ssh_resolve_host erweitert einen SSH-Host-Alias zu Verbindungsparametern.

Befehls-Tools

proc_exec

{
  "sessionId": "ssh-1645123456789-1",
  "command": "ls -la /home",
  "cwd": "/tmp",
  "env": {
    "DEBUG": "1"
  },
  "timeoutMs": 30000
}

proc_sudo

{
  "sessionId": "ssh-1645123456789-1",
  "command": "systemctl restart nginx",
  "password": "sudo-password",
  "cwd": "/etc",
  "timeoutMs": 30000
}

Beide geben zurück:

{
  "code": 0,
  "stdout": "command output",
  "stderr": "",
  "durationMs": 245
}

Datei-Tools

• fs_read

{
  "sessionId": "ssh-1645123456789-1",
  "path": "/etc/hosts",
  "encoding": "utf8"
}

• fs_write

{
  "sessionId": "ssh-1645123456789-1",
  "path": "/tmp/config.txt",
  "data": "server_name example.com;\nlisten 80;",
  "mode": 420
}

• fs_stat gibt size, mtime, mode und type zurück.

• fs_list gibt { "entries": [...], "nextToken": "optional" } zurück.

• fs_mkdirp erstellt Verzeichnisse rekursiv.

• fs_rmrf entfernt Dateien oder Verzeichnisse rekursiv.

• fs_rename benennt einen Pfad um oder verschiebt ihn.

Konfigurations- und Automatisierungs-Tools

ensure_package

{
  "sessionId": "ssh-1645123456789-1",
  "name": "nginx",
  "state": "present",
  "sudoPassword": "optional"
}

state unterstützt present und absent.

ensure_service

{
  "sessionId": "ssh-1645123456789-1",
  "name": "nginx",
  "state": "restarted",
  "sudoPassword": "optional"
}

state unterstützt started, stopped, restarted, enabled und disabled.

ensure_lines_in_file

{
  "sessionId": "ssh-1645123456789-1",
  "path": "/etc/hosts",
  "lines": [
    "192.168.1.10 db-server",
    "192.168.1.20 cache-server"
  ],
  "state": "present",
  "createIfMissing": true,
  "sudoPassword": "optional"
}

state unterstützt present und absent.

patch_apply

{
  "sessionId": "ssh-1645123456789-1",
  "path": "/etc/hosts",
  "diff": "@@ -1 +1 @@\n-old\n+new"
}

os_detect

Gibt Remote-Plattform, Distro, Version, Paketmanager, Init-