TermSSH MCP

✨ Warum TermSSH MCP

Die meisten SSH-Tools für KI-Workflows basieren auf dem Prinzip Befehl ausführen → Ausgabe erhalten → fertig.

Das funktioniert nicht, wenn die eigentliche Aufgabe interaktiv ist:

• Installationsprogramme stellen Fragen

• Shells behalten ihren Zustand bei

• Debugging erfordert mehrere Schritte

• Bereitstellungen erfordern Uploads plus Terminal-Steuerung

• Agenten müssen beobachten, reagieren und fortfahren

TermSSH MCP wurde für diese Lücke entwickelt.

Anstatt so zu tun, als sei alles ein einzelner Befehl, bietet es MCP-Clients einen echten Workflow im Operator-Stil:

Shell öffnen → Eingabe schreiben → Ausgabe lesen → Kontext beibehalten → Dateien hochladen → weiterarbeiten

🧠 Was macht es anders

Terminal-zentriert

Interaktive Terminal-Sitzungen sind das Kernmodell, kein nachträglicher Einfall.

Agentenbereit

Entwickelt für MCP-Clients, Coding-Agenten und Automatisierungsschleifen.

Zustandsbehaftete Workflows

Aktive Sitzungen wiederverwenden, damit mehrstufige Aufgaben sich natürlich und zuverlässig anfühlen.

Upload enthalten

Skripte, Konfigurationen, Payloads und generierte Artefakte über SFTP verschieben.

Plattformübergreifend

Funktioniert mit Linux- und Windows-SSH-Zielen.

Saubere Tool-Oberfläche

Fokussierte MCP-Tools für Terminal-Steuerung und Remote-Dateibereitstellung.

🚀 Kernfunktionen

• Interaktive SSH-Terminal-Sitzungen

• Inkrementeller Terminal-Lese-/Schreibfluss

• Standardmäßig verwaltete Wiederverwendung von Terminal-Sitzungen

• Optionale Erstellung erzwungener Multi-Sitzungen

• Lokaler Datei-Upload via SFTP

• Direkter Text- und Base64-Inhalts-Upload

• Unterstützung für Terminal-Größenänderung

• Unterstützung für Linux- und Windows-SSH-Ziele

• MCP-native Schnittstelle für KI-Tools

🧰 Tool-Set

upload-file

Lädt eine lokale Datei vom MCP-Host-Rechner auf den Remote-SSH-Server mittels SFTP hoch.

Parameter

• localPath — lokaler Quellpfad der Datei

• remotePath — Zielpfad auf dem Remote-Host

• createDirectories — erstellt bei Bedarf fehlende übergeordnete Verzeichnisse

• overwrite — überschreibt eine vorhandene Remote-Datei, falls vorhanden

• mode — optionaler POSIX-Modus wie 0644

upload-content

Lädt direkten Text oder Base64-Inhalt auf den Remote-Server hoch.

Parameter

• content — Rohtext oder Base64-Payload

• encoding — utf8 oder base64

• remotePath — Zielpfad auf dem Remote-Host

• createDirectories — erstellt bei Bedarf fehlende übergeordnete Verzeichnisse

• overwrite — überschreibt eine vorhandene Remote-Datei, falls vorhanden

• mode — optionaler POSIX-Modus wie 0644

terminal-start

Startet eine interaktive Remote-Terminal-Sitzung.

Parameter

• cwd — optionales Arbeitsverzeichnis nach dem Shell-Start

• shell — optionale Shell-Binärdatei

• platformHint — auto, linux oder windows

• elevated — versucht bei Konfiguration eine su-Erhöhung

• cols — Terminal-Breite

• rows — Terminal-Höhe

• env — optionale Umgebungsvariablen

• multiSession — auf true setzen, um eine neue verwaltete Sitzung zu erzwingen, anstatt eine bestehende wiederzuverwenden

terminal-write

Schreibt Eingaben in eine aktive Terminal-Sitzung.

Parameter

• sessionId — Ziel-Sitzungs-ID

• input — zu sendender Text

• appendNewline — hängt bei Bedarf automatisch einen Zeilenumbruch an

terminal-read

Liest gepufferte Ausgaben aus einer Terminal-Sitzung.

Parameter

• sessionId — Ziel-Sitzungs-ID

• sinceSequence — gibt nur Ausgaben zurück, die neuer als eine bestimmte Sequenznummer sind

• maxChars — begrenzt die Größe der zurückgegebenen Ausgabe

• waitForMs — optionale kurze Polling-Verzögerung

terminal-resize

Ändert die Größe einer aktiven Terminal-Sitzung.

Parameter

• sessionId — Ziel-Sitzungs-ID

• cols — neue Breite

• rows — neue Höhe

terminal-close

Schließt eine Terminal-Sitzung lokal.

Parameter

• sessionId — Ziel-Sitzungs-ID

🔄 Typischer Workflow

flowchart LR
    A[terminal-start] --> B[terminal-write]
    B --> C[terminal-read]
    C --> D{Need file?}
    D -- Yes --> E[upload-file / upload-content]
    D -- No --> F{Continue session?}
    E --> F
    F -- Yes --> B
    F -- No --> G[terminal-close]

Dies funktioniert besonders gut für:

• interaktive Paketinstallationen

• Remote-Einrichtung und Provisionierung

• Bereitstellungen mit Artefakt-Upload

• Debugging von Diensten über mehrere Schritte hinweg

• zustandsbehaftete Shell-Workflows, bei denen der Kontext wichtig ist

🛠 Installation

Repository klonen

git clone https://github.com/rayss868/termssh-mcp.git
cd termssh-mcp
npm install
npm run build

Global installieren

npm install -g termssh-mcp

⚙ Konfiguration

Erforderliche CLI-Parameter

• host — Hostname oder IP-Adresse der Remote-Maschine

• user — SSH-Benutzername

Optionale CLI-Parameter

• port — SSH-Port, Standard 22

• password — SSH-Passwort

• key — Pfad zu einem privaten SSH-Schlüssel

• sudoPassword — optionales Passwort für sudo-orientierte Workflows

• suPassword — optionales Passwort für su-basierte Erhöhung

• timeout — SSH-Bereitschafts-Timeout in Millisekunden, Standard 60000

• maxChars — Validierungslimit für die Befehlslänge, Standard 1000; verwenden Sie none oder 0 für den unbegrenzten Modus

🧩 MCP-Konfigurationsbeispiel

{
  "mcpServers": {
    "termssh-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "termssh-mcp",
        "--",
        "--host=1.2.3.4",
        "--port=22",
        "--user=root",
        "--password=pass",
        "--timeout=30000",
        "--maxChars=none"
      ]
    }
  }
}

Beispiel für SSH-Schlüssel

{
  "mcpServers": {
    "termssh-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "termssh-mcp",
        "--",
        "--host=example.com",
        "--user=root",
        "--key=/path/to/private/key"
      ]
    }
  }
}

🤖 Claude Code Beispiel

Registrieren Sie den Server in Claude Code:

claude mcp add --transport stdio termssh-mcp -- npx -y termssh-mcp -- --host=YOUR_HOST --user=YOUR_USER --password=YOUR_PASSWORD

Mit SSH-Schlüssel-Authentifizierung:

claude mcp add --transport stdio termssh-mcp -- npx -y termssh-mcp -- --host=example.com --user=root --key=/path/to/private/key

Mit erweitertem Timeout:

claude mcp add --transport stdio termssh-mcp -- npx -y termssh-mcp -- --host=192.168.1.100 --user=admin --password=your_password --timeout=120000 --maxChars=none

🎯 Hervorragend geeignet für

Entwickler

• Remote-Shell-Zugriff von KI-Coding-Tools

• zustandsbehaftete Debugging-Sitzungen

• Skript- und Konfigurationsbereitstellung

DevOps / Infra-Teams

• Dienstinspektion

• Bereitstellungsunterstützung

• mehrstufige Remote-Operationen

Agenten-Entwickler

• Terminal-native MCP-Workflows

• wiederverwendbare Sitzungen

• kontrollierte Remote-Automatisierungsschleifen

🏗 Entwicklung

Projekt bauen:

npm run build

Tests ausführen:

npm test

Den MCP Inspector verwenden:

npm run inspect

📁 Projektstruktur

• src/index.ts — MCP-Server-Einstiegspunkt und Tool-Registrierung

• src/ssh-connection-manager.ts — SSH-Verbindung und Handhabung des Terminal-Lebenszyklus

• src/upload.ts — Upload-Helfer und Helfer für Metadaten interaktiver Sitzungen

• src/core.ts — geteilte Validierung und SSH-Utility-Primitive

• test/upload-and-terminal.test.ts — Unit-Abdeckung für Upload/Sitzung

• test/maxChars.test.ts — Abdeckung der Befehlsvalidierung

• test/smoke.ssh.test.ts — Smoke-Tests für das aktuell exportierte Verhalten

🗺 Roadmap-Ideen

• reichhaltigere Inspektion von Sitzungsmetadaten

• bessere Beobachtbarkeit von Remote-Sitzungen

• optionale Funktionen zur Sitzungspersistenz

• mehr Beispiele für Claude Code und MCP-Tools

• Workflow-Vorlagen für die Bereitstellung

🔐 Sicherheitshinweis

TermSSH MCP ermöglicht den Remote-Zugriff auf Systeme über SSH. Verwenden Sie es nur auf Infrastrukturen, die Sie besitzen oder für deren Verwaltung Sie ausdrücklich autorisiert sind.

📜 Lizenz

Veröffentlicht unter der MIT-Lizenz.

🤝 Mitwirken

Beiträge sind willkommen. Siehe CONTRIBUTING.md für Richtlinien zur Mitwirkung und CODE_OF_CONDUCT.md für das erwartete Verhalten.