Ermöglicht es einem AI-Client, sich über SSH mit einem Remote-Server zu verbinden, um Befehle auszuführen, Verzeichnisse aufzulisten sowie Dateien via SFTP hoch- oder herunterzuladen.
Auch bekannt als pulsemcp/mcp-servers, ssh-agent-mcp-server
- Stars
- 81
- Tools
- 14
- Downloads, 30 Tage
- —
- Neueste Version
- 0.1.5
- Letzter Commit
- 9. Okt. 2026
- Lizenz
- MIT
Was ist SSH MCP?
SSH ist ein MCP server. Ermöglicht es einem AI-Client, sich über SSH mit einem Remote-Server zu verbinden, um Befehle auszuführen, Verzeichnisse aufzulisten sowie Dateien via SFTP hoch- oder herunterzuladen. Er stellt 14 Tools bereit, etwa ssh_connection_info, ssh_list_directory, ssh_download.
Zusammenfassung generiert aus dem README des Projekts
Über SSH MCP server
Das Verwalten von Remote-Servern über eine AI-Schnittstelle ist mit diesem MCP server möglich, der es einem AI-Client erlaubt, über SSH mit Remote-Maschinen zu interagieren. Er wurde für Entwickler und Systemadministratoren entwickelt, die Remote-Aufgaben erledigen müssen, ohne ihre Chat-Oberfläche verlassen zu müssen. Der Server unterstützt die Authentifizierung über einen SSH agent, was ideal für die sichere Nutzung von passwortgeschützten Keys ist, oder direkt über einen Pfad zu einer Private-Key-Datei.
Nutzer können eine Vielzahl von Aufgaben ausführen, darunter das Ausführen von Shell-Befehlen mit ssh_execute, das Durchsuchen von Remote-Dateisystemen mit ssh_list_directory und das Übertragen von Dateien mittels ssh_upload und ssh_download via SFTP. Um die Sicherheit zu gewährleisten, enthält der Server Tool-Groups, mit denen du den Zugriff auf readonly, write oder admin-Level einschränken kannst. Zudem verfügt er über einen Health Check beim Start, der die Konnektivität und die Credentials sofort nach dem Launch verifiziert. So wird sichergestellt, dass die Erreichbarkeit des Hosts und die Authentifizierung gültig sind, bevor du mit deinem Workflow beginnst.
Was du damit machen kannst
- 1Remote-Shell-Befehle ausführenEine AI kann spezifische Shell-Befehle auf einem Remote-Host ausführen, um Systemaufgaben zu erledigen.
- 2Dateien via SFTP übertragenDu kannst eine AI anweisen, Dateien zwischen deinem lokalen Rechner und einem Remote-Server zu verschieben.
- 3Remote-Verzeichnisse durchsuchenEine AI kann den Inhalt eines Remote-Dateisystems inspizieren, um bestimmte Dateien zu finden.
- 4AI-Berechtigungen einschränkenEntwickler können die AI darauf beschränken, Dateien nur anzuzeigen, indem sie nur die readonly Tool-Group aktivieren.
Geschrieben aus dem README des Projekts. Jeder Use Case wurde gegen ein Zitat daraus geprüft.
So installierst du SSH MCP
Formate geprüft am 10. Nov. 2026Zu Cursor hinzufügenZu Goose hinzufügenSSH MCP in Claude Code installieren
$ claude mcp add --env 'SSH_HOST=<SSH_HOST>' --env 'SSH_USERNAME=<SSH_USERNAME>' --env 'SSH_PASSPHRASE=<YOUR_SSH_PASSPHRASE>' ssh -- npx -y ssh-agent-mcp-serverSSH MCP in Cursor installieren
~/.cursor/mcp.json
{
"mcpServers": {
"ssh": {
"command": "npx",
"args": [
"-y",
"ssh-agent-mcp-server"
],
"env": {
"SSH_HOST": "<SSH_HOST>",
"SSH_USERNAME": "<SSH_USERNAME>",
"SSH_PASSPHRASE": "<YOUR_SSH_PASSPHRASE>"
}
}
}
}SSH MCP in VS Code installieren
.vscode/mcp.json
{
"servers": {
"ssh": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"ssh-agent-mcp-server"
],
"env": {
"SSH_HOST": "<SSH_HOST>",
"SSH_USERNAME": "<SSH_USERNAME>",
"SSH_PASSPHRASE": "<YOUR_SSH_PASSPHRASE>"
}
}
}
}SSH MCP in VS Code CLI installieren
$ code --add-mcp '{"name":"ssh","type":"stdio","command":"npx","args":["-y","ssh-agent-mcp-server"],"env":{"SSH_HOST":"<SSH_HOST>","SSH_USERNAME":"<SSH_USERNAME>","SSH_PASSPHRASE":"<YOUR_SSH_PASSPHRASE>"}}'SSH MCP in Claude Desktop installieren
claude_desktop_config.json
{
"mcpServers": {
"ssh": {
"command": "npx",
"args": [
"-y",
"ssh-agent-mcp-server"
],
"env": {
"SSH_HOST": "<SSH_HOST>",
"SSH_USERNAME": "<SSH_USERNAME>",
"SSH_PASSPHRASE": "<YOUR_SSH_PASSPHRASE>"
}
}
}
}SSH MCP in Codex installieren
$ codex mcp add ssh --env 'SSH_HOST=<SSH_HOST>' --env 'SSH_USERNAME=<SSH_USERNAME>' --env 'SSH_PASSPHRASE=<YOUR_SSH_PASSPHRASE>' -- npx -y ssh-agent-mcp-serverSSH MCP in Codex config.toml installieren
~/.codex/config.toml
[mcp_servers.ssh] command = "npx" args = ["-y", "ssh-agent-mcp-server"] [mcp_servers.ssh.env] SSH_HOST = "<SSH_HOST>" SSH_USERNAME = "<SSH_USERNAME>" SSH_PASSPHRASE = "<YOUR_SSH_PASSPHRASE>"
SSH MCP in Gemini CLI installieren
$ gemini mcp add -s user -e 'SSH_HOST=<SSH_HOST>' -e 'SSH_USERNAME=<SSH_USERNAME>' -e 'SSH_PASSPHRASE=<YOUR_SSH_PASSPHRASE>' ssh npx -- -y ssh-agent-mcp-serverSSH MCP in Gemini settings.json installieren
~/.gemini/settings.json
{
"mcpServers": {
"ssh": {
"command": "npx",
"args": [
"-y",
"ssh-agent-mcp-server"
],
"env": {
"SSH_HOST": "<SSH_HOST>",
"SSH_USERNAME": "<SSH_USERNAME>",
"SSH_PASSPHRASE": "<YOUR_SSH_PASSPHRASE>"
}
}
}
}SSH MCP tools 14
Erkannt aus dem READMEssh_connection_infossh_list_directoryssh_downloadssh_uploadssh_executereadonlywriteadmincommandcwdtimeoutlocalPath
| ssh_connection_info | — | |
| ssh_list_directory | — | |
| ssh_download | — | |
| ssh_upload | — | |
| ssh_execute | — | |
| readonly | — | |
| write | — | |
| admin | — | |
| command | — | |
| cwd | — | |
| timeout | — | |
| localPath | — |
Alle 14 Tools anzeigenWeniger Tools anzeigen
remotePathpath
| remotePath | — | |
| path | — |
Konfiguration
SSH_HOSTErforderlichHostname or IP address of the SSH server.
SSH_USERNAMEErforderlichUsername for SSH authentication.
SSH_PASSPHRASESecretPassphrase for encrypted private key.
ENABLED_TOOLGROUPSComma-separated list of tool groups to enable (readonly, write, admin).
HEALTH_CHECK_TIMEOUTHealth check timeout in milliseconds.
SKIP_HEALTH_CHECKSSkip SSH connection health check on startup.
SSH_AUTH_SOCKPath to SSH agent socket for agent-based authentication.
SSH_COMMAND_TIMEOUTDefault command activity timeout in milliseconds.
SSH_PORTSSH port number.
SSH_PRIVATE_KEY_PATHPath to private key file for direct key authentication.
SSH_TIMEOUTConnection timeout in milliseconds.
| Name | Beschreibung | Typ |
|---|---|---|
| SSH_HOST | Hostname or IP address of the SSH server. | Erforderlich |
| SSH_USERNAME | Username for SSH authentication. | Erforderlich |
| SSH_PASSPHRASE | Passphrase for encrypted private key. | Secret |
| ENABLED_TOOLGROUPS | Comma-separated list of tool groups to enable (readonly, write, admin). | |
| HEALTH_CHECK_TIMEOUT | Health check timeout in milliseconds. | |
| SKIP_HEALTH_CHECKS | Skip SSH connection health check on startup. | |
| SSH_AUTH_SOCK | Path to SSH agent socket for agent-based authentication. | |
| SSH_COMMAND_TIMEOUT | Default command activity timeout in milliseconds. | |
| SSH_PORT | SSH port number. | |
| SSH_PRIVATE_KEY_PATH | Path to private key file for direct key authentication. | |
| SSH_TIMEOUT | Connection timeout in milliseconds. |
Automatisierte Checks
Geluften am 12. Nov. 2026Vollständiger Bericht →Unsere automatisierten Checks bestanden. Das ist kein Security-Audit: Lies den Code und gib dem Server nur den minimal notwendigen Zugriff. Wie die Checks funktionieren
- Source Repository verknüpft und erreichbarBestanden
- Open Source Lizenz (OSI)Bestanden
- Commit oder Release im letzten JahrBestanden
- Package-Name ähnelt keinem populären PackageBestanden
- Remote Endpoint nutzt HTTPSNicht geprüft
- Destruktive Tools sind markiertBestanden
- Keine versteckten Anweisungen an das ModellBestanden
- Keine kritischen Advisories im Paket oder seinen AbhängigkeitenBestanden
README
Auf GitHub ansehenSSH MCP Server
An MCP (Model Context Protocol) server for SSH remote server management with SSH agent authentication support.
This server solves a common problem with SSH MCP servers: support for passphrase-protected SSH keys. By using SSH agent authentication, you can securely connect to remote servers without exposing your key passphrase.
Highlights
- SSH Agent Authentication - Seamlessly works with passphrase-protected SSH keys via SSH agent
- Private Key File Support - Alternative authentication via direct private key file
- Startup Health Check - Verifies SSH connectivity on startup with clear error messages
- Command Execution - Run shell commands on remote servers
- File Transfer - Upload and download files via SFTP
- Directory Listing - Browse remote file systems
- Tool Groups - Control which tools are available (readonly, write, admin)
Authentication Priority
The server supports multiple authentication methods and will use them in this order:
- SSH Agent (recommended) - If
SSH_AUTH_SOCKis set or auto-detected - Private Key File - If
SSH_PRIVATE_KEY_PATHis set
Both methods can be configured simultaneously. If SSH agent authentication is available, it takes priority. The private key file method is used as a fallback or when the agent is not available.
Capabilities
Tools
| Tool | Group | Description |
|---|---|---|
ssh_connection_info |
readonly, write, admin | Get configured SSH connection information |
ssh_list_directory |
readonly, write, admin | List directory contents on remote server |
ssh_download |
readonly, write, admin | Download file from remote server via SFTP |
ssh_upload |
write, admin | Upload file to remote server via SFTP |
ssh_execute |
admin | Execute shell command on remote server |
Resources
| Resource | Description |
|---|---|
ssh://config |
SSH connection configuration and status (for debugging) |
Tool Groups
Control which tools are available via the ENABLED_TOOLGROUPS environment variable:
| Group | Description |
|---|---|
readonly |
Safe operations (connection info, list, download) |
write |
File modifications (upload) |
admin |
Full access including command execution |
Examples:
ENABLED_TOOLGROUPS="readonly"- Only allow browsing and downloadsENABLED_TOOLGROUPS="readonly,write"- Allow file transfers but no command execution- Not set - All tools enabled (default)
Startup Health Check
The server performs an SSH connection health check on startup to verify that the configured credentials and host are valid. This provides immediate feedback if there are configuration issues, rather than discovering them during workflow.
Benefits:
- Faster feedback: Configuration errors surface at startup rather than mid-workflow
- Clearer error messages: Startup failures include hints for common issues
- Improved user experience: Eliminates ambiguity about server operational status
Configuration:
SKIP_HEALTH_CHECKS=true- Skip the health check (useful for lazy connection scenarios)HEALTH_CHECK_TIMEOUT=10000- Customize the health check timeout (default: 10 seconds)
Error hints provided for:
- Authentication failures (SSH key not loaded, wrong key)
- Connection timeouts (host unreachable)
- Connection refused (SSH server not running)
- DNS resolution errors (invalid hostname)
Quick Start
Installation
npx ssh-agent-mcp-server
Or install globally:
npm install -g ssh-agent-mcp-server
Configuration
Environment Variables
| Variable | Required | Description | Default |
|---|---|---|---|
SSH_HOST |
Yes | Hostname or IP address of the SSH server | - |
SSH_USERNAME |
Yes | Username for SSH authentication | - |
SSH_PORT |
No | SSH port number | 22 |
SSH_AUTH_SOCK |
No | Path to SSH agent socket | Auto-detected |
SSH_PRIVATE_KEY_PATH |
No | Path to private key file | - |
SSH_PASSPHRASE |
No | Passphrase for encrypted private key | - |
SSH_TIMEOUT |
No | Connection timeout in milliseconds | 30000 |
SSH_COMMAND_TIMEOUT |
No | Default command activity timeout in milliseconds | 60000 |
ENABLED_TOOLGROUPS |
No | Comma-separated tool groups | All enabled |
SKIP_HEALTH_CHECKS |
No | Skip SSH connection health check on startup | false |
HEALTH_CHECK_TIMEOUT |
No | Health check timeout in milliseconds | 10000 |
Claude Desktop Configuration
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
{
"mcpServers": {
"ssh": {
"command": "npx",
"args": ["-y", "ssh-agent-mcp-server"],
"env": {
"SSH_HOST": "192.168.1.100",
"SSH_USERNAME": "deploy",
"SSH_AUTH_SOCK": "${SSH_AUTH_SOCK}"
}
}
}
}
Restart Claude Desktop and you should be ready to go!
SSH Agent Authentication (Recommended)
SSH agent authentication is the recommended method for passphrase-protected keys:
-
Ensure your SSH agent is running with your key loaded:
# Check if agent is running ssh-add -l # If not, add your key ssh-add ~/.ssh/id_ed25519 -
Pass the
SSH_AUTH_SOCKenvironment variable to the MCP server
The server will automatically use the agent for authentication, and your passphrase-protected key stays secure in the agent.
How It Works
- Your passphrase-protected key is loaded into the SSH agent via
ssh-add - The agent exposes a Unix socket at
$SSH_AUTH_SOCK - This MCP server connects to that socket via the
ssh2library - The agent signs authentication challenges using your decrypted key
- Your private key never leaves the agent - the MCP server never sees it
This is more secure than:
- Storing your passphrase in environment variables
- Using unprotected private keys
- Manually entering passphrases
Tool Details
ssh_execute
Execute a command on the remote server.
Parameters:
command(required): Shell command to executecwd(optional): Working directorytimeout(optional): Activity timeout in milliseconds (default: 60000 orSSH_COMMAND_TIMEOUT)
Activity-based Timeout:
The timeout is activity-based rather than absolute. It resets whenever stdout or stderr output is received from the command. This allows long-running commands that produce periodic output (like builds, deployments, or claude -p commands) to complete successfully, while still timing out commands that hang with no activity.
For commands with delayed initial output (10-30+ seconds before any output), you can:
- Increase the default timeout via
SSH_COMMAND_TIMEOUTenvironment variable - Pass a higher
timeoutparameter for specific commands
Example:
{
"command": "ls -la /var/log",
"cwd": "/home/user"
}
Example with extended timeout for long-running commands:
{
"command": "npm run build",
"timeout": 300000
}
Returns: JSON with stdout, stderr, and exit code
ssh_upload
Upload a file to the remote server via SFTP.
Parameters:
localPath(required): Absolute path to local fileremotePath(required): Destination path on server
ssh_download
Download a file from the remote server via SFTP.
Parameters:
remotePath(required): Path on remote serverlocalPath(required): Local destination path
ssh_list_directory
List directory contents on the remote server.
Parameters:
path(required): Directory path to list
Returns: JSON array with filename, type, size, permissions, modified time
ssh_connection_info
Get information about the configured SSH connection.
Returns: JSON with host, port, username, and authentication details
Development
# Install dependencies
npm run install-all
# Build
npm run build
# Run in development mode
npm run dev
# Run tests
npm test
npm run test:integration
License
MIT
SSH MCP Fragen
Wie füge ich SSH MCP zu Claude Code hinzu?
Führe claude mcp add --env 'SSH_HOST=<SSH_HOST>' --env 'SSH_USERNAME=<SSH_USERNAME>' --env 'SSH_PASSPHRASE=<YOUR_SSH_PASSPHRASE>' ssh -- npx -y ssh-agent-mcp-server in deinem Terminal aus. Füge --scope user hinzu, damit der Server in jedem Projekt verfügbar ist.
Wie füge ich SSH MCP zu Cursor hinzu?
Öffne ~/.cursor/mcp.json und füge den Server unter mcpServers hinzu, mit der Cursor-Config aus dem Installationsabschnitt oben.
Welche Tools bietet SSH MCP?
Er stellt 14 Tools bereit, darunter ssh_connection_info, ssh_list_directory, ssh_download, ssh_upload, ssh_execute.
Wie geht der SSH MCP server mit passwortgeschützten SSH-Keys um?
Die Authentifizierung erfolgt über deinen SSH agent. So bleibt dein entschlüsselter Key im Agenten und wird niemals an den Server weitergegeben. Du lädst deinen Key mit ssh-add und übergibst SSH_AUTH_SOCK an den Server.
Welche Authentifizierungsmethoden unterstützt der SSH MCP server und in welcher Reihenfolge?
Er versucht es zuerst mit dem SSH agent, falls SSH_AUTH_SOCK gesetzt oder automatisch erkannt wird, und nutzt dann als Fallback eine Private-Key-Datei, die über SSH_PRIVATE_KEY_PATH konfiguriert ist.
Wie kann ich einschränken, was der SSH MCP server tun darf?
Setze die Umgebungsvariable ENABLED_TOOLGROUPS auf readonly, write oder admin (oder eine Kombination). Wenn sie nicht gesetzt ist, sind alle Tools aktiviert.
Prüft der SSH MCP server die Verbindung beim Start?
Ja, er führt beim Start einen SSH-Connection-Health-Check durch und gibt Hinweise bei Authentifizierungsfehlern, Timeouts, abgelehnten Verbindungen oder DNS-Fehlern. Du kannst dies mit SKIP_HEALTH_CHECKS=true überspringen.
Was macht das ssh_execute Tool und wie funktioniert sein Timeout?
Es führt einen Shell-Befehl auf dem Remote-Server aus und gibt stdout, stderr sowie den Exit-Code zurück. Das Timeout basiert auf der Aktivität und wird bei jedem Eintreffen von Output zurückgesetzt; der Standardwert liegt bei 60000 ms oder SSH_COMMAND_TIMEOUT.