@yawlabs/ssh-mcp

👁 npm version
👁 License: MIT

Mache SSH fit für KI-Tools. Ein MCP-Server, der deine SSH-Umgebung verwaltet, Fehler diagnostiziert, sie behebt und deinem Agenten Fernzugriff auf alles ermöglicht.

Entwickelt und gepflegt von Yaw Labs.

Das Problem

KI-CLI-Tools laufen in Subprozessen, in denen SSH ständig fehlschlägt. Der Agent versucht git pull und erhält Permission denied (publickey). Er versucht, sich per SSH mit einem Server zu verbinden, und der Agent-Socket ist veraltet. Er versucht zu deployen, und der Host-Key hat sich geändert, weil die Instanz neu erstellt wurde. Jedes Mal weiß die KI nicht, was los ist, und gerät in eine Sackgasse.

Dies passiert in jeder Situation, die SSH-Keys erfordert:

• Git — clone, pull, push, fetch, submodules, LFS

• Paketmanager — npm install, pip install, go get, cargo, composer aus privaten Repos

• Serverzugriff — SSH, SCP, SFTP, rsync

• Tunneling — Port-Weiterleitung zu Datenbanken, SOCKS-Proxys

• Deployment — Ansible, Terraform, Capistrano, Deploy-Skripte

• Cloud — AWS EC2, GCP, Azure, DigitalOcean, jeder VPS

ssh-mcp behebt dies. Es verwaltet den SSH-Agenten, lädt Keys, diagnostiziert Fehler mit umsetzbaren Korrekturbefehlen und bietet Remote-Operationen an – alles als MCP-Tools, die dein KI-Agent aufrufen kann.

Schnellstart

npm install -g @yawlabs/ssh-mcp

Füge dies zu deiner MCP-Client-Konfiguration hinzu:

{
 "mcpServers": {
 "ssh": {
 "command": "ssh-mcp"
 }
 }
}

Tools

Verwaltung der SSH-Umgebung

Tools, die deine lokale SSH-Einrichtung reparieren, damit alles andere – Git, Deploys, Tunnel – nicht mehr abbricht.

Diagnosen

Remote-Operationen

Operationen auf höherer Ebene

Tools, die gängige Muster kapseln, die Agenten mit ssh_exec erstellen – schneller und weniger fehleranfällig.

Automatische Diagnosen

Wenn eine Remote-Operation fehlschlägt, führt ssh-mcp automatisch Diagnosen durch und fügt die Ergebnisse in die Fehlerantwort ein. Dein Agent muss ssh_diagnose nicht separat aufrufen – er erfährt direkt in der Fehlermeldung, was falsch ist und wie es behoben werden kann.

Verbindungs-Pooling

Remote-Operationen verwenden SSH-Verbindungen automatisch wieder. Wenn dein Agent mehrere Aufrufe an denselben Host tätigt, öffnet der erste Aufruf eine Verbindung und nachfolgende Aufrufe nutzen diese wieder. Verbindungen werden nach der letzten Nutzung 60 Sekunden lang offen gehalten und dann automatisch geschlossen.

Unterstützung für SSH-Konfiguration

Alle Verbindungen respektieren deine ~/.ssh/config. Host-Aliase, benutzerdefinierte Ports, Benutzernamen, Identitätsdateien und ProxyJump-Einstellungen werden automatisch verwendet. Wenn du Host myserver in deiner SSH-Konfiguration konfiguriert hast, übergib einfach host: "myserver" – ssh-mcp löst alles auf.

ProxyJump / Bastion-Hosts werden automatisch unterstützt. Wenn deine SSH-Konfiguration ProxyJump bastion für einen Host enthält, verbindet sich ssh-mcp transparent über den Bastion-Host. Verkettete Proxys funktionieren ebenfalls.

Host-Key-Verifizierung

Alle Remote-Operationen verifizieren den Host-Key des Servers gegen ~/.ssh/known_hosts:

• Bekannter Host, Key stimmt überein — akzeptieren.

• Bekannter Host, Key hat sich geändert — ablehnen (MITM-Schutz).

• Unbekannter Host — bei der ersten Verbindung akzeptieren (TOFU). Verwende ssh_known_hosts_fix, um den Key für zukünftige Abweichungserkennungen zu fixieren.

Für strengere Umgebungen setze SSH_MCP_STRICT_HOST_KEY=1, um unbekannte Hosts abzulehnen. Füge sie zuerst explizit mit ssh_known_hosts_fix hinzu.

Die Diagnose-Tools (ssh_test, ssh_diagnose) verwenden StrictHostKeyChecking=no für ihre Testbefehle. Diese Tests führen nur echo SSH_OK aus – es werden keine Anmeldedaten oder Daten übertragen –, daher ist die gelockerte Einstellung für Konnektivitätstests sicher. Echte Operationen laufen immer über den hostVerifier.

Windows-Unterstützung

Unter Windows erkennt ssh-mcp den OpenSSH Authentication Agent-Dienst automatisch (über die Named Pipe \\.\pipe\openssh-ssh-agent). Es ist kein SSH_AUTH_SOCK erforderlich – stelle nur sicher, dass der OpenSSH-Agent-Dienst läuft.

Authentifizierung

Alle Remote-Operationen akzeptieren Verbindungsparameter:

Reihenfolge der Auth-Auflösung: ssh-mcp wählt die erste Übereinstimmung aus dieser Liste und geht nicht zu späteren Einträgen über – dies macht die Auth-Methode deterministisch und vorhersehbar.

1. Expliziter privateKeyPath

2. Explizites password

3. ssh-agent (SSH_AUTH_SOCK unter Unix, \\.\pipe\openssh-ssh-agent unter Windows)

4. Identitätsdateien aus ~/.ssh/config für den Host

5. Standard-Key-Pfade (~/.ssh/id_ed25519, id_rsa, id_ecdsa)

Beispiel-Workflows

Agent kann kein Git-Pull durchführen

Agent calls ssh_git_check → "Permission denied. Your SSH key is not registered with github.com."
Agent calls ssh_key_list → finds id_ed25519 exists but is not loaded
Agent calls ssh_key_load("~/.ssh/id_ed25519") → "Key loaded"
Agent calls ssh_git_check → "Git SSH authentication to github.com succeeded as username"
Agent runs git pull → works

Host-Key nach Instanz-Neuerstellung geändert

Agent calls ssh_exec on server → error: "Host key verification failed"
 (auto-diagnostics included in error: "Fix with ssh_known_hosts_fix")
Agent calls ssh_known_hosts_fix("my-server") → "Host key refreshed"
Agent calls ssh_exec → works

Erstmalige Verbindung zu einem neuen Server

Agent calls ssh_test("new-server") → "Connection refused at new-server:22"
Agent calls ssh_diagnose("new-server") → full report showing agent running, keys loaded, but host unreachable
Agent reports: "SSH server isn't running on new-server or port 22 is blocked"

Programmatische Nutzung

import { connect, exec, diagnose, ensureAgent, listSshKeys, checkGitSsh, ConnectionPool } from '@yawlabs/ssh-mcp';

// Fix SSH environment
const agent = ensureAgent();
console.log(agent.message);

// Check git access
const git = checkGitSsh('github.com');
console.log(git.message);

// List available keys
const keys = listSshKeys();
for (const key of keys) {
 console.log(`${key.name} (${key.type}) - ${key.loadedInAgent ? 'loaded' : 'not loaded'}`);
}

// Run a remote command (one-off)
const client = await connect({ host: 'my-server', username: 'deploy' });
const result = await exec(client, 'uptime');
console.log(result.stdout);
client.end();

// Run multiple commands with connection pooling
const pool = new ConnectionPool();
await pool.withConnection({ host: 'my-server' }, async (client) => {
 const r1 = await exec(client, 'uptime');
 console.log(r1.stdout);
});
// Connection stays open for 60s — next call reuses it
await pool.withConnection({ host: 'my-server' }, async (client) => {
 const r2 = await exec(client, 'df -h');
 console.log(r2.stdout);
});
pool.drain(); // close all connections when done

// Diagnose issues
const report = diagnose('my-server');
console.log(report.overall); // "ok" | "warning" | "error"
for (const check of report.checks) {
 console.log(`[${check.status}] ${check.name}: ${check.message}`);
}

Anforderungen

• Node.js 18+

• SSH-Client installiert (für Diagnosen und Umgebungsverwaltung)

Lizenz

MIT

Maintenance

Resources

• NPM Package
• GitHub Repository
Need Help?Related Servers

Tools

• ssh_agent_ensureA
• ssh_config_lookupA
• ssh_deleteA
• ssh_diagnoseA
• ssh_downloadB
• ssh_execA
• ssh_findB
• ssh_git_checkA