MCP Connector #

Der MCP Connector macht eine owncloud.online-Instanz zum Server für das Model Context Protocol (MCP). KI-Assistenten, Editoren und eigene Agenten listen, lesen und durchsuchen darüber Dateien. Schaltet ein Administrator den Schreibzugriff ein, schreiben und teilen sie auch. Jeder Aufruf läuft mit den Rechten des angemeldeten Kontos, ab Werk nur lesend.

Voraussetzungen #

Installation #

Die App liegt dem Server bei und wird nur eingeschaltet:

sudo -u www-data php8.4 occ app:enable oco_mcp

Der Endpunkt lautet https://cloud.example.com/apps/oco_mcp/mcp. Enthalten die Adressen Ihrer Instanz index.php, heißt er https://cloud.example.com/index.php/apps/oco_mcp/mcp.

Einrichtung #

App-Passwort anlegen #

Jedes Konto legt sein App-Passwort selbst an:

1. Einstellungen → Persönlich → Sicherheit öffnen, Abschnitt App-Passwörter / Token.
2. Unter App-Name einen Namen eintragen, etwa „MCP Laptop“, und Neuen App-Passcode erstellen klicken.
3. Benutzername und Passwort / Token in den Client übernehmen. Das Passwort zeigt die Seite nur dieses eine Mal. Mit Erledigt schließen.

Der Client meldet sich per HTTP Basic an: Anmeldename und App-Passwort, mit Doppelpunkt verbunden und Base64-kodiert. Den Wert für die Kopfzeile erzeugen Sie so:

# -w0 verhindert Zeilenumbrüche in der Ausgabe; unter macOS ohne -w0
printf '%s' 'alice:<app-passwort>' | base64 -w0
# Kopfzeile: Authorization: Basic <Ausgabe>

Das Papierkorb-Symbol (Trennen) neben dem Eintrag widerruft das App-Passwort. Der Zugang endet sofort, weil der Server die Anmeldedaten bei jeder Anfrage neu prüft.

Schreibzugriff freischalten #

Ab Werk bietet der Server nur lesende Werkzeuge an. Schreibende Werkzeuge und die schreibende Verwaltung von Konten und Gruppen brauchen beide Werte:

sudo -u www-data php8.4 occ config:app:set oco_mcp enable_write --value yes
sudo -u www-data php8.4 occ config:app:set oco_mcp write_groups --value "mcp-schreiben,admin"

Seit owncloud.online 11.0.14 gilt eine leere write_groups als „niemand“. Vorher hieß sie „alle Konten“. Steht enable_write auf yes und write_groups ist leer, schreibt der Server einmal am Tag eine Warnung ins Protokoll: „MCP write tools are unavailable: "enable_write" is set but "write_groups" is empty …“.

Die meisten Clients laden die Liste der Werkzeuge nur beim Verbinden. Verbinden Sie den Client nach einer Änderung neu.

Weitere Einstellungen hat die App nicht. Anmeldung und Rechte kommen aus owncloud.online selbst.

Client anbinden #

Clients mit „Streamable HTTP“ brauchen nur die Adresse des Endpunkts und die Kopfzeile Authorization: Basic ….

Desktop-Clients, die MCP-Server nur als lokale Programme starten, binden den Endpunkt über die Brücke mcp-remote an, ein npm-Paket. Dafür brauchen Sie Node.js mit npx. Ein Eintrag im Abschnitt mcpServers der Client-Konfiguration sieht so aus:

{
  "mcpServers": {
    "owncloud-online": {
      "command": "npx",
      "args": [
        "-y", "mcp-remote",
        "https://cloud.example.com/apps/oco_mcp/mcp",
        "--header", "Authorization:${AUTH_HEADER}",
        "--transport", "http-only"
      ],
      "env": {
        "AUTH_HEADER": "Basic <Base64 von alice:app-passwort>"
      }
    }
  }
}

Die Kopfzeile steht ohne Leerzeichen in args, der Wert mit Leerzeichen in env. Manche Clients unter Windows reichen Leerzeichen in args nicht richtig weiter. --transport http-only passt zum Server: Er antwortet mit JSON und bietet keinen Ereignisstrom per GET an.

Den Base64-Wert erzeugen Sie unter Windows in der PowerShell so:

[Convert]::ToBase64String([Text.Encoding]::UTF8.GetBytes('alice:<app-passwort>'))

Weitere Clients und den Ablauf des Protokolls im Detail beschreibt die Seite MCP Connector (KI-Anbindung).

Verbindung testen #

Eine Sitzung beginnt mit initialize. Die Antwort enthält die Kopfzeile Mcp-Session-Id, die jede weitere Anfrage mitschicken muss.

curl -s -D - -u 'alice:<app-passwort>' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}' \
  https://cloud.example.com/apps/oco_mcp/mcp

curl -s -u 'alice:<app-passwort>' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -H 'Mcp-Session-Id: <ID aus der ersten Antwort>' \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}' \
  https://cloud.example.com/apps/oco_mcp/mcp

Der Server kennt die Protokollversionen 2024-11-05, 2025-03-26, 2025-06-18 und 2025-11-25 und antwortet mit der Version, die der Client anfragt. Eine Sitzung verfällt nach einer Stunde ohne Anfrage. Ein DELETE auf den Endpunkt mit der Sitzungs-ID beendet sie sofort.

Nutzung #

Werkzeuge #

Werkzeuge, die ein Konto nicht nutzen darf, nennt der Server gar nicht erst. Die genauen Parameter liefert tools/list.

• files_read liefert ab Werk bis 1 MiB, mit max_bytes bis 10 MiB.
• files_list gibt höchstens 1000 Einträge je Aufruf zurück, shares_list höchstens 500.
• files_delete löscht über die normale Datei-Schnittstelle. Ist die App files_trashbin aktiv, landet die Datei unter Gelöschte Dateien.
• Freigaben entstehen über die normale Freigabe-Logik. Die Vorgaben unter Einstellungen → Administration → Teilen gelten auch hier.

Dateien als Ressourcen #

Zusätzlich stellt der Server die Dateien des Kontos als MCP-Ressourcen bereit:

• owncloud:/// liefert den Stammordner als JSON-Liste. Jeder Eintrag trägt eine uri, die sich direkt lesen lässt.
• owncloud:///{path} liest eine Datei oder einen Ordner. Schrägstriche in verschachtelten Pfaden werden als %2F geschrieben, etwa owncloud:///Dokumente%2Fbericht.txt.

Text kommt als UTF-8, Binärdaten als Base64, jeweils bis 5 MiB.

Fragen an Dokumente #

Ist die App AI Documents eingeschaltet, erscheint das Werkzeug ai_ask. Es beantwortet eine Frage aus den analysierten Dokumenten des Kontos und nennt die Quellen. Parameter: question, scope (all, folder oder selection), path bei folder, file_ids (durch Kommas getrennt) bei selection und mode (qa, summary, extract oder report). Ohne AI Documents fehlt das Werkzeug, ein Fehler ist das nicht.

Grenzen und Hinweise #

• Der Endpunkt nimmt nur HTTP Basic mit App-Passwort an. Browser-Sitzungen (Cookies), Bearer-Token und das normale Kennwort weist er ab. Eine Zwei-Faktor-Pflicht lässt sich so nicht umgehen.
• Fehlversuche bremsen weitere Versuche von derselben Adresse und für denselben Anmeldenamen. Im Protokoll stehen sie als MCP login failed: '<login>' (Remote IP: '<adresse>'). Ein fail2ban-Filter auf „Login failed“ erfasst diese Zeilen nicht, ergänzen Sie ihn um „MCP login failed“. Hinter einem Reverse-Proxy braucht die Bremse gegen Passwort-Raten richtig gesetzte trusted_proxies, siehe Sicherheit und Setup-Warnungen.
• Steht der Host aus der Kopfzeile Origin oder, ohne sie, aus Host weder in trusted_domains noch in overwritehost und ist er nicht localhost, 127.0.0.1 oder [::1], antwortet der Server mit 403. Einträge mit * in trusted_domains zählen dabei nicht. Clients, die im Browser auf einer fremden Website laufen, verbinden sich deshalb nicht.
• Eine Anfrage darf höchstens 2 MiB groß sein.
• Pfade mit . oder .. lehnt der Server ab.
• Fehler aus AI Documents erreichen den Client nur als allgemeine Meldung. Die Ursache steht im Serverprotokoll unter oco_mcp.
• Sitzungen liegen als Dateien im Datenverzeichnis unter oco_mcp-sessions.
• Wie Sie eigene Werkzeuge ergänzen, beschreibt die README der App im Server-Repository.

Fehlersuche #