ftp-deploy-mcp

Der Deploy-Button für KI-Coding-Agenten. Claude Code · Claude Desktop · Cursor · Windsurf · Trae · Antigravity → deine eigenen FTP / FTPS / SFTP-Server.

Version française → README.fr.md

Dein Agent führt den Deploy aus — du fragst einfach.

Warum

• Jedes Webprojekt endet gleich: „Jetzt noch auf den Server damit.“

• KI-Agenten schreiben großartigen Code, aber die meisten haben keinen sicheren Weg, ihn auf klassisches Hosting zu bringen — OVH, Ionos, Hostinger, o2switch und der Rest der Shared-Hosting-Welt läuft immer noch über FTP/SFTP, nicht über git push.

• ftp-deploy-mcp gibt jedem MCP-Client einen Deploy-Weg zu deiner eigenen Infrastruktur — im selben Gespräch, in dem der Code geschrieben wurde.

• Anders als generische SSH-Exec-MCP-Server ist dieser gezielt für Datei-Deployments gebaut: eine Pfad-Jail, ein Read-only-Modus, Dry-run und Zugangsdaten, die nie in den Kontext des Modells gelangen.

Related MCP server: mcp-remote-ssh

Funktionen

Schnellstart

1. git clone https://github.com/alebgl77/ftp-deploy-mcp.git && cd ftp-deploy-mcp

2. Führe install.cmd aus (Doppelklick, Windows) oder ./install.sh (macOS / Linux).

3. Starte deine IDE neu und sag deinem Agenten: „Deploy ./dist to prod.“

So funktioniert es

flowchart LR
subgraph agents [AI agents]
  A[Claude Code]; B[Cursor]; C[Windsurf]; D[Trae]; E[Antigravity]
end
agents -- MCP stdio --> S[ftp-deploy-mcp<br/>10 tools · path jail · read-only guard]
S -- FTP / FTPS --> F[(your web hosts)]
S -- SFTP --> G[(your servers)]
K[ftp-servers.json<br/>credentials stay local] -.-> S

1. Was es ist

Ein MCP-Server (Model Context Protocol), der über stdio läuft und 10 Tools für deinen Coding-Agenten bereitstellt. Zugangsdaten liegen in einer lokalen Konfigurationsdatei und gelangen nie in den Kontext des LLM. Jede Remote-Operation ist auf ein root beschränkt, das du pro Server festlegst.

Benötigt Node.js >= 18. Keine nativen Abhängigkeiten, nichts zu kompilieren.

2. Installation

⚡ Ein-Befehl-Installation (empfohlen)

git clone https://github.com/alebgl77/ftp-deploy-mcp.git
cd ftp-deploy-mcp

Starte dann den Assistenten:

• Windows: Doppelklick auf install.cmd.

• macOS / Linux: ./install.sh (falls nötig zuerst chmod +x install.sh).

• Oder manuell: npm install && npm run setup.

Der setup-Assistent erledigt alles für dich:

• erstellt oder importiert deine Serverkonfiguration (einschließlich FileZilla-Import deiner vorhandenen Sites);

• testet die Verbindung zu jedem Server;

• schreibt automatisch die Konfigurationsdateien der erkannten MCP-Clients (Claude Code, Claude Desktop, Cursor, Windsurf, Antigravity) — mit einem .backup-<Datum>-Backup, bevor eine vorhandene Datei verändert wird;

• gibt einen einfügefertigen Block aus (und kopiert ihn) für Trae, das über seine UI konfiguriert wird.

Starte dann deine IDE neu und sag deinem Agenten z. B.: „Liste meine FTP-Server auf.“

Diagnose und Optionen

Jederzeit verfügbar: eine read-only-Diagnose (schreibt nichts):

npm run doctor          # or: node src/index.js doctor

Sie zeigt die Node-Version, welche Konfigurationsdatei verwendet wird, die Serverliste (niemals Passwörter) und — pro Client — ob der ftp-Eintrag mit dieser Installation verdrahtet ist.

setup-Optionen (node src/index.js setup [optionen]):

(b) Globale Installation

npm install -g .

Der Befehl ftp-deploy-mcp ist jetzt in deinem PATH; verwende ihn statt node .../src/index.js.

(c) Auf npm veröffentlichen (für npx -y-Nutzung)

Wenn du dieses Paket unter deinem eigenen Namen auf npm veröffentlichst, können Clients es ohne vorherige Installation ausführen:

{ "command": "npx", "args": ["-y", "your-package-name"] }

3. Serverkonfiguration

Erstelle eine Datei ftp-servers.json. Der Server sucht sie in dieser Reihenfolge (die erste gefundene gewinnt):

1. --config <pfad> (Kommandozeilen-Flag)

2. Umgebungsvariable FTP_MCP_CONFIG (Pfad zur JSON-Datei)

3. ./ftp-servers.json (aktuelles Arbeitsverzeichnis)

4. ~/.ftp-mcp/servers.json

Vollständiges Schema

{
  "defaultServer": "prod",          // optional: used when "server" is not given
  "servers": {
    "prod": {
      "protocol": "sftp",           // REQUIRED: "ftp" | "ftps" | "sftp"
      "host": "ssh.example.com",    // REQUIRED
      "port": 22,                    // optional (defaults: ftp/ftps 21, implicit ftps 990, sftp 22)
      "user": "deploy",             // REQUIRED
      "password": "${ENV:PROD_PW}", // optional: password (or an env placeholder)
      "privateKeyPath": "~/.ssh/id_ed25519", // optional (sftp); "~" is expanded
      "passphrase": "…",            // optional: private-key passphrase
      "root": "/var/www/site",      // optional (default "/"): ALL ops are jailed under it
      "readOnly": false,             // optional: blocks upload/deploy/mkdir/rename/delete
      "insecureTLS": false,           // optional (ftps): skip certificate checks — requires "allowInsecure"
      "implicitTLS": false,          // optional (ftps): implicit TLS (port 990, legacy servers)
      "allowInsecure": false         // optional: explicit opt-in REQUIRED for plain "ftp" or "insecureTLS"
    }
  }
}

Der Block oben verwendet //-Kommentare nur zur Veranschaulichung. Die echte Datei muss strenges JSON sein (keine Kommentare). Siehe ftp-servers.example.json.

Ersetzung durch Umgebungsvariablen

Jeder String-Wert darf ${ENV:VARIABLE_NAME} enthalten. Er wird beim Start durch den Wert der Umgebungsvariable ersetzt. Ist die Variable nicht gesetzt, geben die Tools eine klare Fehlermeldung mit dem Namen der fehlenden Variable aus.

"password": "${ENV:OVH_FTP_PASSWORD}"

Sicherheitstipps

• Bevorzuge SFTP. Reines ftp und ftps mit insecureTLS: true werden standardmäßig abgelehnt: Bei diesen Transporten kann ein Netzwerkangreifer Zugangsdaten und Dateien abfangen oder verändern. Um sie trotzdem zu verwenden, musst du auf dem jeweiligen Server explizit "allowInsecure": true setzen — und jeder Start-Log sowie jedes Tool-Ergebnis trägt dann eine sichtbare Sicherheitswarnung.

• Nimm ftp-servers.json in deine .gitignore auf (in diesem Repo bereits erledigt).

• Beschränke die Dateirechte (chmod 600 ftp-servers.json unter Unix).

• Bevorzuge Umgebungsvariablen (${ENV:…}) oder einen SSH-Schlüssel gegenüber einem Klartextpasswort.

• Verwende readOnly: true für Server, auf die der Agent niemals schreiben darf.

• Setze root so eng wie möglich: Die Jail verhindert jeden ../-Ausbruch.

4. Import aus FileZilla

Hast du deine Sites bereits in FileZilla? Konvertiere sie:

# Auto-detect the default sitemanager.xml location…
node src/index.js import-filezilla

# …or an explicit file, written to an ftp-servers.json
node src/index.js import-filezilla --file /path/sitemanager.xml --out ./ftp-servers.json

Ohne --out wird das JSON auf stdout ausgegeben. Base64-kodierte Passwörter werden dekodiert; Sites ohne gespeichertes Passwort erhalten einen ${ENV:<NAME>_PASSWORD}-Platzhalter (die Variable setzt du selbst). Beispielausgabe:

{
  "defaultServer": "my-site",
  "servers": {
    "my-site": {
      "protocol": "ftp",
      "host": "ftp.example.com",
      "user": "deploy",
      "password": "…",
      "root": "/www/html"
    }
  }
}

Achtung: Die erzeugte Datei enthält dekodierte Klartextpasswörter — halte sie aus der Versionskontrolle heraus (.gitignore) und beschränke ihre Rechte (chmod 600).

Reine-FTP-Sites: Importierte Server mit "protocol": "ftp" (wie im Beispiel oben) werden beim Verbindungsaufbau abgelehnt, bis du sie entweder auf sftp/ftps umstellst oder explizit "allowInsecure": true bei ihnen setzt — der Import gibt für jede solche Site eine Warnung aus. Siehe Sicherheit.

5. Manuelle Client-Einrichtung (falls du setup nicht verwendest)

npm run setup schreibt diese Dateien automatisch (mit Backups). Dieser Abschnitt ist nur nützlich, wenn du lieber alles von Hand verdrahtest.

Ersetze /absolute/path/to/ftp-deploy-mcp/src/index.js durch den echten Pfad (Schrägstriche / funktionieren auch unter Windows). Wenn du das Paket auf npm veröffentlicht hast, ersetze "command": "node", "args": ["…/src/index.js"] durch "command": "npx", "args": ["-y", "dein-paketname"].

Die unten angegebenen Dateipfade sind die Standardpfade zum Zeitpunkt der Erstellung dieser Dokumentation; die UIs dieser Produkte entwickeln sich weiter, also prüfe bei Bedarf deren Doku.

Claude Code

.mcp.json im Projektstamm:

{
  "mcpServers": {
    "ftp": {
      "command": "node",
      "args": ["/absolute/path/to/ftp-deploy-mcp/src/index.js"]
    }
  }
}

Oder in einem Befehl:

claude mcp add ftp -- node /absolute/path/to/ftp-deploy-mcp/src/index.js

Claude Desktop

• Windows: %APPDATA%\Claude\claude_desktop_config.json

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

• Linux: ~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "ftp": {
      "command": "node",
      "args": ["/absolute/path/to/ftp-deploy-mcp/src/index.js"]
    }
  }
}

Cursor

~/.cursor/mcp.json (global) oder .cursor/mcp.json (Projekt):

{
  "mcpServers": {
    "ftp": {
      "command": "node",
      "args": ["/absolute/path/to/ftp-deploy-mcp/src/index.js"]
    }
  }
}

Windsurf

~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "ftp": {
      "command": "node",
      "args": ["/absolute/path/to/ftp-deploy-mcp/src/index.js"]
    }
  }
}

Trae

Trae hat keine stabile Konfigurationsdatei — alles läuft über die UI. KI-Chat-Panel → Einstellungen/Zahnrad → MCP → Hinzufügen → Manuell konfigurieren, dann einfügen (das ist der Block, den setup ausgibt und in deine Zwischenablage kopiert):

{
  "mcpServers": {
    "ftp": {
      "command": "node",
      "args": ["/absolute/path/to/ftp-deploy-mcp/src/index.js"]
    }
  }
}

Antigravity

Je nach Version ist die Datei eine der folgenden:

• ~/.gemini/antigravity/mcp_config.json

• Variante: ~/.gemini/config/mcp_config.json

{
  "mcpServers": {
    "ftp": {
      "command": "node",
      "args": ["/absolute/path/to/ftp-deploy-mcp/src/index.js"]
    }
  }
}

Du kannst auch das MCP-Panel des Agenten (MCP-Serververwaltung) → Server hinzufügen verwenden, mit derselben Struktur.

6. Die 10 Tools

Alle Remote-Pfade (path, remote_path, …) sind relativ zum Server-root und verwenden POSIX-Stil. Der Parameter server ist immer optional (siehe Auflösung unten).

Serverauflösung: expliziter server-Parameter → defaultServer → der einzige Server, falls es nur einen gibt → andernfalls ein Fehler, der die verfügbaren Namen auflistet.

Standard-Ausschlüsse für ftp_deploy: **/node_modules/**, **/.git/**, .env, .env.*, *.log, .DS_Store, Thumbs.db, ftp-servers.json, **/.ftp-mcp/** (deine exclude-Globs werden hinzugefügt; include schränkt auf passende Dateien ein). Muster ohne Schrägstrich treffen auf jeder Tiefe zu (gitignore-artig): auch ein verschachteltes apps/api/.env wird ausgeschlossen.

7. Beispiel-Prompts

• „./dist auf dem prod-Server bereitstellen."

• „Auflisten, was in /www auf ovh liegt."

• „Die .htaccess von prod holen und mir zeigen."

• „Einen Probelauf der Bereitstellung von ./build nach /www machen, damit ich sehen kann, was gesendet würde."

• „index.old.html auf prod in index.html umbenennen."

8. Sicherheit

• Standardmäßig sichere Übertragung: einfaches FTP und FTPS mit deaktivierter Zertifikatsprüfung (insecureTLS: true) werden verweigert, sofern der Servereintrag nicht explizit "allowInsecure": true setzt. Wenn erlaubt, wird beim Start, in ftp_list_servers, in doctor und an jedes Tool-Ergebnis für diesen Server eine Sicherheitswarnung angehängt.

• Root-Gefängnis: jede Operation wird normalisiert und dann verifiziert, dass sie unterhalb des Server-root bleibt. Jeder Ausbruchsversuch (../…) wird verweigert, selbst wenn root / ist.

• Nur-Lesen: readOnly: true blockiert jeden Schreibzugriff (Upload, Deploy, mkdir, rename, delete); Lesezugriffe funktionieren weiterhin.

• Zugangsdaten außerhalb der LLM: Passwörter, Passphrasen und Schlüssel werden niemals in der Tool-Ausgabe zurückgegeben.

• Keine Telemetrie, keine ausgehenden Verbindungen außer zu deinen eigenen Servern.

• Verbindungen pro Aufruf: jedes Tool öffnet eine Verbindung, führt die Operation aus und schließt sie — keine dauerhafte Sitzung.

9. Fehlerbehebung

• Timeout / keine Verbindung (FTP): meist ist der Passivmodus durch eine Firewall blockiert. Stelle sicher, dass die Passiv-Ports deines Servers erreichbar sind.

• SFTP-Schlüssel-Authentifizierung: setze privateKeyPath (~ wird expandiert) und, falls der Schlüssel verschlüsselt ist, passphrase. Prüfe die Berechtigungen des Schlüssels.

• „INSECURE CONNECTION REFUSED": Der Server verwendet einfaches FTP oder FTPS mit deaktivierter Zertifikatsprüfung. Stelle auf sftp (oder ftps mit einem gültigen Zertifikat) um — oder, nur wenn du das Abhörrisiko vollständig akzeptierst — setze "allowInsecure": true auf diesem Server.

• Selbstsigniertes FTPS: insecureTLS: true akzeptiert ein unverifiziertes Zertifikat. Dies deaktiviert den Schutz vor Man-in-the-Middle-Angriffen, erfordert daher ebenfalls "allowInsecure": true und gibt bei jedem Aufruf eine Sicherheitswarnung aus. Bevorzuge die Installation eines gültigen Zertifikats.

• Implizites FTPS (Port 990): setze implicitTLS: true (ftps-Protokoll) für ältere Server, die ab dem ersten Byte verschlüsseln, ohne einen AUTH TLS-Befehl.

• „no server configured": Die Datei wurde an keiner der 4 Speicherorte gefunden. Erstelle ftp-servers.json oder übergib --config <path> / FTP_MCP_CONFIG=<path>.

• Der Client sieht die Tools nach setup nicht: starte die IDE vollständig neu (schließe jedes Fenster, nicht nur das Projekt) und überprüfe dann die Verkabelung mit npm run doctor.

• Der Server startet trotz ungültiger Konfiguration: das ist beabsichtigt (MCP-Clients mögen keine Server, die beim Start sterben). Der genaue Fehler wird beim Start auf stderr ausgegeben und bei jedem Tool-Aufruf zurückgegeben.

Entwicklung

npm test          # runs the full smoke test (local FTP + SFTP, no external network)
node src/index.js --version
node src/index.js --help

Mitwirken

Beiträge sind willkommen — siehe CONTRIBUTING.md für das Entwicklungs-Setup, die Prinzipien des Projekts und die PR-Checkliste.

Sicherheit

Eine Schwachstelle gefunden? Bitte kein öffentliches Issue eröffnen — siehe SECURITY.md für die Meldung auf privatem Weg.

Lizenz

MIT — siehe LICENSE.