SSH Remote File MCP Server

Dateien auf einem Remote-Server über Claude Code lesen, bearbeiten und Befehle ausführen — als wären die Dateien lokal.

Ein MCP-Server, der einen Remote-SSH-Host als eine Reihe von Dateisystem-Tools bereitstellt. Nach der Registrierung bei Claude Code können Sie ihn bitten, /home/you/proj/main.py zu lesen, eine Funktion zu bearbeiten, pytest auszuführen oder über den Remote-Baum zu greppen — und er kommuniziert über SSH mit dem Server, mit Pfad-Scoping und Befehls- Filterung auf dem Weg.

中文文档 / Chinesische Version → · GitHub →

Lizenz

MIT — siehe LICENSE.

Related MCP server: MCP SSH Server

Funktionen

Schnellstart

# 1. Clone and enter
git clone https://github.com/zhangqi-eiq/server_mcp.git
cd server_mcp

# 2. Install (editable mode — picks up code changes immediately)
python install.py

# 3. Edit your real credentials
#    (file is at ~/.ssh-mcp-server/config.json by default)

# 4. Restart Claude Code, then in a chat:
#    "show me the env of my server"

Das war's. install.py erledigt drei Dinge:

1. pip install -e . — installiert das Paket.

2. Kopiert config.json (mit Platzhalterwerten) nach ~/.ssh-mcp-server/.

3. Führt claude mcp add aus, sodass der Server in Claude Code erscheint.

Falls Sie die claude-CLI noch nicht haben, führen Sie python install.py --no-register aus und fügen den MCP-Eintrag von Hand hinzu (siehe Manuelle Konfiguration).

Manuelle Konfiguration

Wenn Sie die Dinge lieber von Hand einrichten möchten, oder install.py nicht korrekt registriert hat:

1. Das Paket installieren

pip install -e .

Dadurch wird ssh_mcp_server in den Python-Importpfad aufgenommen, sodass python -m ssh_mcp_server den Server starten kann.

2. Ihre Konfiguration erstellen

Kopieren Sie config.json nach ~/.ssh-mcp-server/config.json (der Loader sucht dort, wenn SSH_MCP_CONFIG nicht gesetzt ist) und füllen Sie echte Werte ein:

mkdir -p ~/.ssh-mcp-server
cp config.json ~/.ssh-mcp-server/config.json
$EDITOR ~/.ssh-mcp-server/config.json

3. Bei Claude Code registrieren

Der MCP-Eintrag muss den Server über den Python-Interpreter aufrufen, in den Sie installiert haben. <python> unten sollte der absolute Pfad zu diesem Interpreter sein (sys.executable aus Ihrer aktivierten Umgebung, z. B. C:\Users\you\.conda\envs\myenv\python.exe unter Windows oder /home/you/.venv/bin/python unter Linux).

Option A — Benutzerbereich, in jedem Projekt verfügbar:

claude mcp add --scope user ssh-remote \
  -e SSH_MCP_CONFIG="$HOME/.ssh-mcp-server/config.json" \
  -- "<python>" -m ssh_mcp_server

Option B — Projektbereich, nur für dieses Projekt:

Erstellen Sie .mcp.json in Ihrem Projektstamm:

{
  "mcpServers": {
    "ssh-remote": {
      "command": "<absolute path to python>",
      "args": ["-m", "ssh_mcp_server"],
      "env": {
        "SSH_MCP_CONFIG": "/absolute/path/to/your/config.json"
      }
    }
  }
}

Hinweis: Claude Code sucht an zwei Orten nach mcpServers — in ~/.claude.json (CLI-verwaltet, geschrieben von claude mcp add) und in ~/.claude/settings.json (manuell bearbeitet). Der CLI-Weg oben schreibt automatisch in die richtige Datei.

Konfigurationsreferenz

Form von config.json:

{
  "ssh": {
    "host": "your-server.example.com",
    "port": 22,
    "username": "your-username",
    "auth": {
      "type": "password",
      "key_path": "",
      "password": "your-password",
      "key_password": ""
    },
    "connect_timeout": 10,
    "keepalive_interval": 30
  },
  "allowed_paths": [
    "/home/your-username/projects"
  ],
  "security": {
    "blocked_commands": ["rm -rf /", "mkfs", ...],
    "max_file_size_mb": 50,
    "max_output_chars": 100000,
    "command_timeout": 30
  }
}

SSH-Verbindung

Zugriffskontrolle

• allowed_paths — Whitelist der Remote-Verzeichnisse. Jede Dateioperation wird gegen diese Liste validiert, nach der ..-Normalisierung. Anfragen außerhalb der Liste werden abgelehnt. Unterpfade erben den Zugriff (z. B. erlaubt /data/proj /data/proj/sub/file.py).

• security.blocked_commands — Liste von Shell-Befehlsmustern, die ssh_run_command sich weigert auszuführen. Die Standardwerte decken offensichtliche Gefahrenquellen ab (rm -rf /, mkfs, shutdown, Fork-Bomben, direkte Schreibzugriffe auf Blockgeräte). Sie können die Liste erweitern, aber schwächen Sie sie niemals ab, um einen legitimen Bedarf zu "beheben" — siehe Sicherheitsmodell.

Ressourcenlimits

Authentifizierung

Schlüsselbasiert (empfohlen)

# On your local machine
ssh-keygen -t ed25519 -C "you@example.com"

# Push the public key to the remote
ssh-copy-id -i ~/.ssh/id_ed25519.pub user@server

Dann in config.json:

"auth": {
  "type": "key",
  "key_path": "~/.ssh/id_ed25519",
  "key_password": ""
}

key_password wird nur benötigt, wenn der private Schlüssel selbst verschlüsselt ist.

Passwortbasiert

"auth": {
  "type": "password",
  "password": "your-password"
}

Das Passwort wird im Klartext in config.json gespeichert. Bevorzugen Sie die Schlüssel-Authentifizierung.

GUI-Manager (optional)

Eine kleine Tk-basierte GUI ermöglicht es Ihnen, mehrere Serverprofile zu verwalten und zwischen ihnen zu wechseln:

# From source
python server_manager.py

# Or build a standalone Windows exe and put it on PATH
pip install -e ".[gui]"   # adds pyinstaller
python build.py
python setup_global.py
# now `SSH-Server-Manager` is on PATH

Profile liegen in profiles.json; beim Wechseln wird das ausgewählte Profil in config.json kopiert, sodass der MCP-Server es beim nächsten Start übernimmt.

Sicherheitsmodell

Dieser Server ist bewusst konservativ. Zwei unabhängige Ebenen schützen den Remote-Host:

1. Pfad-Scoping. Jede Dateioperation wird normalisiert (Auflösen von .., Zusammenfassen von Schrägstrichen) und dann gegen allowed_paths geprüft. Es gibt keine Möglichkeit, die Liste zu umgehen — die Prüfung erfolgt serverseitig, nachdem der Pfad auf dem Remote aufgelöst wurde.

2. Befehlsfilterung. ssh_run_command lehnt jeden Befehl ab, der mit security.blocked_commands übereinstimmt (Teilstring-Match). Die Standardliste blockiert rekursive Zerstörung, direkte Geräteschreibzugriffe, System-Herunterfahren, Fork-Bomben und Remote-Shell-Installer (curl … | sh). Erweitern Sie die Liste, wenn Sie etwas Bestimmtes erlauben müssen — aber entkernen Sie sie nicht.

Dinge, die dieser Server nicht tut:

• Er läuft nicht als Root auf dem Remote. SSH zu einem Nicht-Root-Benutzer.

• Er umgeht kein sudo. Wenn der konfigurierte Benutzer kein sudo kann, kann es der Server auch nicht.

• Er bietet keine interaktive Shell. Langlaufende Prozesse werden durch command_timeout beendet.

Fehlerbehebung

Projektstruktur

server/
├── ssh_mcp_server/         # MCP server package (the actual product)
│   ├── server.py           #   tool definitions
│   ├── ssh_client.py       #   paramiko wrapper
│   ├── security.py         #   path + command validation
│   └── config.py           #   config loader
├── server_manager.py       # Tk GUI for managing profiles
├── profiles.json           # GUI profile store
├── config.json             # runtime config template (placeholder values)
├── setup.py                # pip-installable package metadata
├── install.py              # one-shot installer (install + register)
├── setup_global.py         # optional: deploy GUI exe to PATH
├── build.py                # optional: PyInstaller wrapper for the GUI
├── SSH-Server-Manager.spec # PyInstaller spec for fine-grained builds
├── requirements.txt        # raw dependency pins
├── LICENSE                 # MIT
├── README.md               # this file (English)
└── README.zh.md            # Chinese translation

Lizenz

MIT — siehe die Datei für den vollständigen Text.