mcp-synology

MCP-Server für Synology NAS-Geräte. Stellt die Funktionen der Synology DSM-API als MCP-Tools bereit, die Claude verwenden kann.

Migration von synology-mcp

Wenn Sie von synology-mcp (v0.3.x oder früher) aktualisieren, beachten Sie bitte, dass das Paket umbenannt wurde. Ein Migrationsskript übernimmt automatisch die Konfiguration, den Status, die Keyring-Einträge und die Konfiguration von Claude Desktop:

# Download and run the migration script
curl -O https://raw.githubusercontent.com/cmeans/mcp-synology/main/scripts/migrate-from-synology-mcp.py
python migrate-from-synology-mcp.py          # dry run — preview changes
python migrate-from-synology-mcp.py --apply  # apply changes

Das Skript migriert:

• Konfigurationsverzeichnis (~/.config/synology-mcp/ → ~/.config/mcp-synology/)

• Statusverzeichnis (~/.local/state/synology-mcp/ → ~/.local/state/mcp-synology/)

• Keyring-Anmeldedaten

• Claude Desktop claude_desktop_config.json (aktualisiert Befehl und Pfade)

Siehe CHANGELOG.md für vollständige Details zu den Breaking Changes.

Unterstützte Module

File Station

Durchsuchen, suchen, übertragen und verwalten Sie Dateien auf Ihrem NAS. 14 Tools in zwei Berechtigungsstufen:

• READ — list_shares, list_files, list_recycle_bin, search_files, get_file_info, get_dir_size, download_file

• WRITE — create_folder, rename, copy_files, move_files, delete_files, restore_from_recycle_bin, upload_file

System

Überwachen Sie den Zustand und die Ressourcennutzung Ihres NAS. 2 schreibgeschützte Tools:

• get_system_info — Modell, Firmware-Version, RAM, Temperatur, Betriebszeit (funktioniert für alle Benutzer)

• get_resource_usage — Live-CPU-Auslastung, Speicherauslastung, Festplatten-I/O, Netzwerkdurchsatz (erfordert Administratorkonto)

Funktionen

• Interaktive Einrichtung — geführte Konfiguration, die Ihre Konfiguration erstellt, Anmeldedaten speichert, 2FA handhabt und ein Claude Desktop-Snippet ausgibt

• Berechtigungsstufen — READ oder WRITE pro Modul, erzwungen bei der Tool-Registrierung

• 2FA-Unterstützung — automatisch erkannt; Geräte-Token-Bootstrap mit automatischer, stiller Re-Authentifizierung

• Sichere Anmeldedaten — OS-Keyring-Integration, die transparent unter macOS, Windows und Linux funktioniert (einschließlich Claude Desktop). Siehe docs/credentials.md.

• Multi-NAS — verwalten Sie mehrere NAS-Geräte mit separaten Konfigurationen, Anmeldedaten und Status

Schnellstart

1. Einrichtung ausführen

uvx mcp-synology setup

Erfordert uv. uvx lädt die neueste Version automatisch herunter und führt sie aus – kein separater Installationsschritt erforderlich.

Die Einrichtung fragt nach Ihrem NAS-Host, Anmeldedaten und Präferenzen. Wenn für Ihr Konto 2FA aktiviert ist, werden Sie nach einem OTP-Code gefragt und ein Geräte-Token für zukünftige automatische Anmeldungen gespeichert.

Am Ende wird ein Claude Desktop JSON-Snippet ausgegeben, das Sie kopieren und einfügen können.

2. Zu Claude Desktop hinzufügen

Kopieren Sie das Snippet aus der Einrichtung in Ihre claude_desktop_config.json und starten Sie Claude Desktop neu. Es sieht in etwa so aus:

{
  "mcpServers": {
    "synology-nas": {
      "command": "uvx",
      "args": ["mcp-synology", "serve", "--config", "~/.config/mcp-synology/nas.yaml"]
    }
  }
}

Der Name der Konfigurationsdatei (z. B. nas.yaml) dient auch als natürlicher Bezeichner für die Verbindung – Sie können ihn passend zu Ihrem NAS benennen (z. B. home-nas.yaml, office-nas.yaml).

Unter Linux erkennt der Server automatisch den D-Bus-Sitzungs-Socket für den Keyring-Zugriff. Falls die automatische Erkennung fehlschlägt, fügen Sie "env": {"DBUS_SESSION_BUS_ADDRESS": "unix:path=/run/user/<uid>/bus"} zur Claude Desktop-Konfiguration hinzu. Der Einrichtungsbefehl enthält dies bereits im generierten Snippet.

3. Überprüfung

uvx mcp-synology check                # Validates credentials work
uvx mcp-synology setup --list         # Shows all configured NAS instances

Alternative: Globale Installation

Wenn Sie eine dauerhafte Installation bevorzugen (vermeidet den Download bei jedem Aufruf):

uv tool install mcp-synology
mcp-synology setup
mcp-synology check

Alternative: Nur-Umgebungsvariablen-Modus

Es ist keine Konfigurationsdatei erforderlich, wenn SYNOLOGY_HOST gesetzt ist. Dies ist nützlich für Docker- oder CI-Umgebungen:

{
  "mcpServers": {
    "synology": {
      "command": "uvx",
      "args": ["mcp-synology", "serve"],
      "env": {
        "SYNOLOGY_HOST": "192.168.1.100",
        "SYNOLOGY_USERNAME": "your_user",
        "SYNOLOGY_PASSWORD": "your_password"
      }
    }
  }
}

Oder über die CLI:

SYNOLOGY_HOST=192.168.1.100 uvx mcp-synology check

2FA-Unterstützung

mcp-synology unterstützt DSM-Konten mit Zwei-Faktor-Authentifizierung vollständig. Dies wird automatisch erkannt – Sie müssen nichts weiter konfigurieren:

1. Bootstrap — mcp-synology setup erkennt 2FA, fragt nach Ihrem OTP-Code und speichert ein Geräte-Token im Keyring

2. Stille Re-Authentifizierung — nachfolgende Anmeldungen verwenden automatisch das Geräte-Token (keine OTP-Abfragen)

3. Pro Instanz — jede NAS-Konfiguration erhält ihr eigenes Geräte-Token, sodass gemischte 2FA/Nicht-2FA-Setups problemlos funktionieren

Geräte-Token bleiben bestehen, bis Sie sie explizit in DSM widerrufen (Persönlich > Sicherheit > Anmeldeaktivität). Sie laufen nicht von selbst ab. Wenn ein Token widerrufen wurde, führen Sie mcp-synology setup erneut aus, um den Bootstrap zu wiederholen.

Keyring & Anmeldedaten

Anmeldedaten werden im OS-Keyring gespeichert und transparent abgerufen:

Reihenfolge der Auflösung von Anmeldedaten: Umgebungsvariablen > Konfigurationsdatei > Keyring. Explizite Quellen überschreiben den impliziten Standard.

Für Umgebungen ohne Keyring (Docker, CI) verwenden Sie Umgebungsvariablen oder Inline-Anmeldedaten in der Konfigurationsdatei.

Siehe docs/credentials.md für Keyring-Dienstnamen, Multi-NAS-Einrichtung und Informationen zum Überprüfen/Entfernen gespeicherter Anmeldedaten.

Updates

mcp-synology prüft auf Updates und benachrichtigt Sie in Ihrem Claude Desktop-Chat – die erste Tool-Antwort in jeder Sitzung enthält einen Hinweis, falls eine neuere Version auf PyPI verfügbar ist.

So verwalten Sie Updates über die CLI:

mcp-synology --check-update                 # Check for a newer version
mcp-synology --auto-upgrade enable           # Auto-upgrade on each interactive run
mcp-synology --revert                        # Roll back to previous version
mcp-synology --revert 0.1.0                  # Roll back to a specific version

Um Update-Benachrichtigungen zu deaktivieren, fügen Sie dies Ihrer Konfiguration hinzu (auf oberster Ebene):

# ~/.config/mcp-synology/config.yaml
check_for_updates: false

Konfiguration

Die interaktive Einrichtung erstellt eine Konfigurationsdatei für Sie. Für manuelle Konfiguration oder erweiterte Optionen siehe examples/:

• config-minimal.yaml — einfachstmögliche Konfiguration

• config-power-user.yaml — HTTPS, benutzerdefinierte Timeouts, Protokollierung, Anweisungen

• config-docker.yaml — gesteuert durch Umgebungsvariablen

Multi-NAS

Jedes NAS erhält eine eigene Konfigurationsdatei, Anmeldedaten und einen Claude Desktop-Eintrag. Der Name der Konfigurationsdatei dient als natürlicher Bezeichner (z. B. home-nas.yaml, media-server.yaml).

Setzen Sie alias, um Claude einen Anzeigenamen für die Verbindung zu geben:

# ~/.config/mcp-synology/home-nas.yaml
alias: HomeNAS

Der Alias erscheint im Namen des MCP-Servers (z. B. synology-HomeNAS), damit Claude weiß, mit welchem NAS es kommuniziert.

Benutzerdefinierte Anweisungen

Benutzerdefinierte Anweisungen ermöglichen es Ihnen, die Interaktion von Claude mit Ihren NAS-Tools zu gestalten. Dies ist nützlich, wenn:

• Mehrere NAS-Verbindungen — sagen Sie Claude, welche Verbindung für welche Aufgaben bevorzugt werden soll („verwende dies für Medien, verwende admin für benutzerübergreifende Vorgänge“)

• Sicherheitsvorkehrungen — fügen Sie Regeln hinzu wie „immer vor dem Löschen bestätigen“ oder „niemals /Backups anfassen“

• Kontext — erklären Sie, was sich auf dem NAS befindet („dies ist ein Medienserver, /video enthält unsere Bibliothek, sortiert nach Genre“)

Kontext hinzufügen — custom_instructions wird vor die integrierte Eingabeaufforderung gestellt (höhere Priorität):

# ~/.config/mcp-synology/config.yaml
custom_instructions: |
  This is the admin NAS with elevated privileges.
  Prefer this connection for file operations requiring cross-user access.
  Never delete files from /Backups without explicit confirmation.

Volle Kontrolle — instructions_file ersetzt die integrierte Eingabeaufforderung vollständig. Kopieren Sie die integrierte server.md als Ausgangspunkt:

# ~/.config/mcp-synology/config.yaml
instructions_file: ~/.config/mcp-synology/my-instructions.md

Beide unterstützen Vorlagenvariablen: {display_name}, {instance_id}, {host}, {port}.

Debugging

Zwei Möglichkeiten, Debug-Protokollierung zu aktivieren:

mcp-synology check --verbose                          # --verbose flag on setup/check
SYNOLOGY_LOG_LEVEL=debug mcp-synology serve           # env var, works for all commands

Oder dauerhaft in Ihrer Konfigurationsdatei festlegen:

# ~/.config/mcp-synology/config.yaml
logging:
  level: debug
  file: ~/.local/state/mcp-synology/nas/server.log  # optional, logs to stderr by default

Die Debug-Ausgabe enthält jede DSM-API-Anfrage/Antwort (Passwörter maskiert), Schritte zur Auflösung von Anmeldedaten, Konfigurationserkennung, Versionsaushandlung und Entscheidungen zur Modulregistrierung.

Mitwirken

Siehe DEVELOPMENT.md für Build-Befehle, Tests, Einrichtung von Integrationstests und Designdokumente.

Danksagungen

Dieses Projekt wurde mit einem Spec-First Coding-Ansatz erstellt – einem Modell der Mensch-KI-Zusammenarbeit, bei dem das Design der Implementierung vorausgeht und Spezifikationen den Vertrag zwischen beiden bilden.

Im Gegensatz zum „Vibe Coding“, bei dem man beschreibt, was man möchte, und die KI den Code spontan generieren lässt, behandelt Spec-First Coding das Design als separate, bewusste Phase. Die vier Spezifikationen in docs/specs/ wurden durch ausführliche Gespräche entwickelt – wobei Kompromisse untersucht, Alternativen verworfen und Entscheidungen mit Begründungen dokumentiert wurden. Die Implementierung nutzte dann die Spezifikationen als Quelle der Wahrheit über 11 Build-Phasen hinweg.

Live-Tests mit echter Hardware enthüllten Verhaltensweisen, die die Spezifikationen nicht vorhersehen konnten (DSM-API-Eigenheiten, Drosselung des Suchdienstes, Inkompatibilitäten beim Versionsformat). Diese Entdeckungen sind in CLAUDE.md und im Code dokumentiert, der maßgeblich ist, wo Spezifikationen abweichen.

Lizenz

Apache 2.0