synology-filestation-mcp

Ein MCP (Model Context Protocol)-Dienst, der auf der Synology File Station Web-API basiert. Er ermöglicht es KI-Agenten, Dateien auf Synology NAS direkt zu verwalten: Verzeichnisse durchsuchen, suchen, hochladen/herunterladen, erstellen/umbenennen/kopieren/verschieben/löschen, komprimieren/entpacken usw.

Unterstützt zwei Betriebsmodi:

• Stdio (lokal) (src/index.js): Läuft auf Ihrem lokalen Rechner, Anmeldeinformationen werden in lokalen Umgebungsvariablen gespeichert.

• Streamable HTTP (remote) (src/http.js): Zentral auf einem Server bereitgestellt, mehrere Benutzer teilen sich den Dienst, ihre jeweiligen NAS-Anmeldeinformationen werden über Anfrage-Header übergeben.

Systemanforderungen

• Node.js >= 18 (Entwicklung mit Node 24 getestet; für Server mit niedriger glibc-Version können die unofficial-builds mit glibc-217 verwendet werden)

• DSM 7.x (getestet auf DSM 7.2)

Related MCP server: Synology MCP Server

Installation

npm install

Modus 1: Stdio (lokal)

NAS-Verbindungsinformationen werden über Umgebungsvariablen bereitgestellt (Sie können auch .env.example als .env kopieren und ausfüllen; die Variablen werden beim Start automatisch geladen):

Am Beispiel von Claude Desktop, konfigurieren Sie claude_desktop_config.json:

{
  "mcpServers": {
    "synology-filestation": {
      "command": "node",
      "args": ["D:/path/to/synology-filestation-mcp/src/index.js"],
      "env": {
        "SYNOLOGY_HOST": "http://192.168.1.1:5000",
        "SYNOLOGY_USER": "your_username",
        "SYNOLOGY_PASSWORD": "your_password"
      }
    }
  }
}

Modus 2: HTTP (remote, mehrere Benutzer)

Serverstart:

# .env 或环境变量
SYNOLOGY_HOST=http://192.168.1.1:5000   # 默认 NAS 地址（客户端可用 X-NAS-Host 覆盖）
PORT=3000
MCP_AUTH_TOKEN=<随机令牌>                # 设置后客户端必须带 Bearer token

npm run start:http

Eigenschaften:

• Mehrere Benutzer: Jede MCP-Sitzung hat einen eigenen NAS-Login-Status (sid-Pool), keine Vermischung.

• Anmeldeinformationen-Übergabe: Der Client stellt seine eigenen NAS-Anmeldeinformationen über die Anfrage-Header X-NAS-User / X-NAS-Password bereit. Optional kann X-NAS-Host den serverseitigen Standardwert überschreiben. Fehlen diese, werden die serverseitigen Umgebungsvariablen verwendet (unterstützt serverseitig zentral verwaltete Konten).

• Authentifizierung: Wenn MCP_AUTH_TOKEN gesetzt ist, müssen alle /mcp-Anfragen den Header Authorization: Bearer <token> enthalten.

• Sitzungsverwaltung: Leerlaufsitzungen werden nach 30 Minuten automatisch bereinigt und vom NAS abgemeldet (SESSION_IDLE_TTL_MS ist anpassbar).

• Health-Check: GET /health

Client-Konfiguration (für Clients, die Remote-MCP unterstützen, über URL):

{
  "mcpServers": {
    "synology-filestation": {
      "url": "http://<部署服务器>:3000/mcp",
      "headers": {
        "Authorization": "Bearer <MCP_AUTH_TOKEN>",
        "X-NAS-User": "同事自己的 NAS 账号",
        "X-NAS-Password": "同事自己的 NAS 密码"
      }
    }
  }
}

systemd-Bereitstellungsbeispiel:

[Unit]
Description=Synology FileStation MCP (HTTP)
After=network.target

[Service]
WorkingDirectory=/opt/synology-filestation-mcp
ExecStart=/usr/bin/node src/http.js
Restart=always
RestartSec=3

[Install]
WantedBy=multi-user.target

Sicherheitshinweis: In der Produktion wird die Verwendung von HTTPS (Reverse Proxy) zur TLS-Terminierung empfohlen, um eine Übertragung der NAS-Anmeldeinformationen im Klartext in den Anfrage-Headern zu vermeiden.

Werkzeugliste

Tests

SYNOLOGY_HOST=http://192.168.0.196:5000 SYNOLOGY_USER=xxx SYNOLOGY_PASSWORD=xxx npm test

Der Rauchtest führt eine vollständige Kette auf dem NAS durch: Anmelden → Gemeinsame Ordner auflisten → Verzeichnis erstellen → Hochladen → Inhalt auflisten → Informationen abrufen → Umbenennen → Kopieren → Suchen → Herunterladen und Inhalt verifizieren → Löschen und bereinigen → Abmelden. Der Test erstellt ein temporäres Verzeichnis mcp-smoke-test in einem beschreibbaren gemeinsamen Ordner und löscht es nach Abschluss automatisch.

Es gibt auch einen Erweiterungstest test/extended.mjs (node test/extended.mjs, liest ebenfalls Umgebungsvariablen): Er deckt das bytegenaue Hoch- und Herunterladen von 23 Dateiformaten (Dokumente/Bilder/Videos/Audio/Archive/Datenbanken/VM-Images), Massenkopieren/Verschieben/Löschen, Entpacken auf dem NAS, Überprüfung des Papierkorbs sowie Erkundung der Berechtigungs- und Sicherheitsgrenzen ab.

Implementierungshinweise (DSM 7.x-Kompatibilität)

• Beim Start wird zuerst SYNO.API.Info aufgerufen, um die Pfade und Versionen der einzelnen APIs zu ermitteln. Die Anmeldung erfolgt über SYNO.API.Auth (format=sid).

• Der Parameter additional von SYNO.FileStation.List v2 erwartet ein JSON-Array-Format (z.B. ["size","time"]); kommagetrennte Zeichenketten werden stillschweigend ignoriert.

• Für Dateiinformationsabfragen wird SYNO.FileStation.List / getinfo verwendet (SYNO.FileStation.Info / get gibt die File Station-Serverkonfiguration zurück, keine Dateiinformationen).

• Für Uploads wird API-Version 2 verwendet: In der Praxis funktioniert der Parameter overwrite in v3 nicht, bei gleichnamigen Dateien wird ein 414-Fehler zurückgegeben. Die sid wird sowohl über ein Formularfeld als auch über den Cookie: id=<sid>-Header übergeben.

• Kopieren/Verschieben/Löschen sind asynchrone Vorgänge; SYNO.FileStation.BackgroundTask in DSM 7.x hat nur die Methode list (kein status). Der Fortschritt wird durch Filtern nach taskid abgefragt.

• Die Suche ist ein asynchroner Vorgang; das Werkzeug fragt intern list ab, bis finished erreicht ist.

• Das Zielverzeichnis für SYNO.FileStation.Extract muss bereits existieren, sonst wird ein 408-Fehler (No such file or directory) zurückgegeben.

• SYNO.FileStation.Compress hängt von den Anwendungsberechtigungen des Kontos in DSM ab. Wird ein Fehler 105 (session does not have permission) zurückgegeben, müssen dem Konto in der DSM-Systemsteuerung die entsprechenden Berechtigungen erteilt werden.

Fähigkeitsgrenzen (Nicht im Umfang der File Station API)

Die folgenden Fähigkeiten sind in der offiziellen File Station API nicht vorhanden und können daher von diesem MCP nicht bereitgestellt werden:

• ACL-Berechtigungsverwaltung: Gehört zu den DSM-Systemsteuerungsfunktionen (SYNO.Core.* private Schnittstellen, keine öffentliche File Station API).

• AES-Verschlüsselung gemeinsamer Ordner: Gehört zu den DSM-Speicherverwaltungsfunktionen (Erstellen/Einhängen verschlüsselter gemeinsamer Ordner).

• Manipulationsschutz (Schreibgeschützt/Nicht löschbar): File Station API bietet keinen Einstiegspunkt; kann indirekt durch schreibgeschütztes Einhängen gemeinsamer Ordner erreicht werden.

• Netzwerkpapierkorb: Das Löschverhalten folgt automatisch den Papierkorbeinstellungen der jeweiligen gemeinsamen Ordner (nach dem Aktivieren werden gelöschte Dateien in <share>/#recycle verschoben). Die API muss nichts separat steuern und kann es auch nicht.

Verzeichnisstruktur

src/
  index.js    stdio 入口（本地模式）
  http.js     HTTP 入口（远程模式，Streamable HTTP + 多用户会话池）
  server.js   共享的 MCP Server 构建（注册全部工具）
  env.js      .env 加载
  client.js   Synology API 客户端：API 发现、认证、请求封装、错误码映射
  tools/      每个 File Station API 一个工具模块
test/
  smoke.mjs      对真实 NAS 的全链路冒烟测试（stdio 层逻辑）
  http-smoke.mjs HTTP 模式自测（鉴权、会话、工具调用、会话关闭）
  extended.mjs   扩展能力测试（多格式、批量、解压、回收站）