mcp-ssh-tool

👁 npm version
👁 CI
👁 Security
👁 Official MCP Registry
👁 License: MIT
👁 npm downloads

Produktionsreife MCP-SSH-Automatisierung für Operatoren, Entwickler und KI-Clients. mcp-ssh-tool öffnet persistente SSH-Sitzungen und stellt sichere, strukturierte Tools für die Befehlsausführung, Dateivorgänge, Übertragungen, Tunnel, Paket-/Dienstverwaltung, Metriken, Ressourcen und geführte Prompts bereit.

v2 ist standardmäßig sicher: Strenge Host-Key-Überprüfung ist aktiviert, Root-Login ist deaktiviert, rohes sudo ist richtlinienbasiert eingeschränkt, destruktive Befehle und Dateisystemänderungen sind untersagt, sofern die Richtlinie dies nicht zulässt, und Remote-HTTP startet nur auf dem Loopback-Interface, es sei denn, Bearer-Authentifizierung und erlaubte Ursprünge sind konfiguriert.

Warum dieser Server

• Vertrauen: Zentrale Richtlinien-Engine, strukturierte Audit-Ereignisse, bereinigte Protokolle, strenge Host-Keys und maschinenlesbare Fehler.

• MCP-Qualität: stdio für lokale Clients, Streamable HTTP für Remote-Clients, Legacy-SSE nur hinter einem expliziten Kompatibilitäts-Flag.

• KI-freundliche Tools: Stabile Ausgabeschemata, structuredContent, Annotationen für schreibgeschütztes/destruktives/idempotentes Verhalten, Ressourcen und kuratierte Prompts.

• Betrieb: Sitzungs-TTL/Eviction, Befehls-Timeouts, Prüfsummenüberprüfung bei Übertragungen, echtes SSH-Forwarding, Prometheus-Metriken und OpenTelemetry-Hooks.

• Portabilität: SFTP zuerst, POSIX/BusyBox-fähige Shell-Fallbacks für grundlegende Dateivorgänge und explizite Support-Grenzen.

Schnellstart

Ausführen ohne Installation:

npx -y mcp-ssh-tool --version

Oder global installieren:

npm install -g mcp-ssh-tool

Fügen Sie Ihrem Client einen stdio-MCP-Server hinzu:

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

Verwenden Sie ihn von Ihrem MCP-Client aus:

Open a safe SSH session to prod-1 as deploy, inspect host capabilities, then show disk usage.

Anforderungen

• Node.js 22.22.2+ oder 24.14.1+ (nur LTS)

• SSH-Zugriff auf Ziel-Hosts

• Eine gefüllte known_hosts-Datei für die strenge Host-Überprüfung oder eine explizite Host-Key-Richtlinie pro Sitzung

Transporte

Der Start von HTTP außerhalb des Loopbacks wird verweigert, sofern nicht sowohl --bearer-token-file als auch erlaubte Ursprünge konfiguriert sind.

Sichere Standardeinstellungen

Der Modus policyMode: "explain" pro Sitzung gibt einen Plan/ein Urteil zurück, ohne es auszuführen. Verwenden Sie dies vor Änderungen, wenn ein KI-Client das Risiko zusammenfassen muss.

Richtlinienbeispiel

Setzen Sie SSH_MCP_POLICY_FILE=/etc/mcp-ssh-tool/policy.json:

{
 "mode": "enforce",
 "allowRootLogin": false,
 "allowRawSudo": false,
 "allowDestructiveCommands": false,
 "allowDestructiveFs": false,
 "allowedHosts": ["^prod-[0-9]+\\.example\\.com$"],
 "commandAllow": ["^(uname|df|uptime|systemctl status)\\b"],
 "commandDeny": ["rm\\s+-rf\\s+/", "shutdown", "reboot"],
 "pathAllowPrefixes": ["/tmp", "/var/tmp", "/home/deploy"],
 "pathDenyPrefixes": ["/etc/shadow", "/etc/sudoers", "/boot", "/dev", "/proc"]
}

Einfache Bereitstellungen können Umgebungsvariablen-Überschreibungen wie SSH_MCP_ALLOW_RAW_SUDO=true, SSH_MCP_ALLOWED_HOSTS=prod-1.example.com oder SSH_MCP_PATH_ALLOW_PREFIXES=/tmp,/home/deploy verwenden.

Kern-Tools

• ssh_open_session, ssh_close_session, ssh_list_sessions, ssh_ping, ssh_list_configured_hosts, ssh_resolve_host

• proc_exec, proc_sudo, proc_exec_stream

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

• file_upload, file_download

• ensure_package, ensure_service, ensure_lines_in_file, patch_apply

• os_detect, get_metrics

• tunnel_local_forward, tunnel_remote_forward, tunnel_list, tunnel_close

Alle Tools geben Text sowie stabiles structuredContent zurück. Tool-Metadaten enthalten Titel, Ausgabeschemata und Annotationen, die schreibgeschütztes, destruktives, idempotentes und externes Nebenwirkungsverhalten offenlegen.

Ressourcen und Prompts

Ressourcen:

• mcp-ssh-tool://sessions/active

• mcp-ssh-tool://metrics/json

• mcp-ssh-tool://metrics/prometheus

• mcp-ssh-tool://ssh-config/hosts

• mcp-ssh-tool://policy/effective

• mcp-ssh-tool://audit/recent

• mcp-ssh-tool://capabilities/support-matrix

Prompts:

• safe-connect

• inspect-host-capabilities

• plan-mutation

• managed-config-change

Support-Matrix

Client-Beispiele

ChatGPT oder Claude Desktop:

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

VS Code oder Cursor:

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

MCP Inspector über HTTP:

printf '%s' 'super-secret-token' > .mcp-token
mcp-ssh-tool --transport=http --host 127.0.0.1 --port 3000 --bearer-token-file .mcp-token

Konfiguration

Wichtige Umgebungsvariablen:

Die veralteten Aliase STRICT_HOST_KEY_CHECKING und SSH_MCP_STRICT_HOST_KEY werden für einen v2-Kompatibilitätszyklus noch akzeptiert. Bevorzugen Sie SSH_MCP_HOST_KEY_POLICY.

Entwicklung

Verwenden Sie die exakte lokale Laufzeit aus .nvmrc / .node-version und führen Sie dann aus:

npm ci
npm run check

Live-SSH-Suiten sind optional:

RUN_SSH_INTEGRATION=1 npm run test:integration
RUN_SSH_E2E=1 npm run test:e2e

Lokale Qualitäts-Gates sind geschichtet:

• pre-commit: Formatiert gestagte Dateien und lintet nur gestagtes TypeScript

• pre-push: Führt npm run check:push aus

• task hooks: Führt verfolgte npm-Hooks plus .pre-commit-config.yaml-Hooks aus, wenn pre-commit installiert ist

• manuelle/vollständige Parität: task ci oder npm run check

CI/CD-Eigentümerschaft

Das persönliche Repository https://github.com/oaslananka/mcp-ssh-tool ist das kanonische Quell-Repository. Automatische CI/CD, Supply-Chain-Sicherheitsprüfungen, vertrauenswürdiges npm-Publishing und MCP-Registry-Publishing laufen nur von https://github.com/oaslananka-lab/mcp-ssh-tool. Das Organisations-Repository zieht aus der kanonischen Quelle; Push- und Publish-Workflows des persönlichen Repositorys sind deaktiviert.

Die repository.url des npm-Pakets zeigt absichtlich auf das Organisations-Repository, damit die npm-Provenienz überprüfen kann, ob das veröffentlichte Artefakt aus demselben GitHub-Actions-Repository stammt, das es erstellt hat.

Siehe docs/ci-cd-topology.md für Organisations-Sync, Release-Flow und manuelle Fallback-Anleitungen.

Dokumentation

• ARCHITECTURE.md

• SECURITY_DECISIONS.md

• MIGRATION.md

• docs/ci-cd-topology.md

• docs/development.md

• docs/release.md

• docs/doppler.md

• docs/operations.md

• docs/branch-protection.md

• docs/maintenance-policy.md

• docs/api-stability.md

• docs/threat-model.md

• docs/configuration.md

• docs/security-model.md

• docs/troubleshooting.md

• docs/enterprise-deployment.md

Lizenz

MIT-Lizenz. Siehe LICENSE.

Maintenance

Resources

• NPM Package
• GitHub Repository
Need Help?Related Servers

Tools

• connector_statusA
• ensure_lines_in_fileA
• ensure_packageC
• ensure_serviceB
• file_downloadA
• file_uploadB
• fs_listC
• fs_mkdirpA