nextcloud-collectives-mcp

Ein MCP-Server (Model Context Protocol) für den Zugriff auf die Nextcloud Collectives App. Damit können MCP-Clients (z.B. Claude Code) Collectives (Team-Wikis), deren Seiten und Tags auflisten, lesen und bearbeiten.

Voraussetzungen

• Node.js 22+

• Eine Nextcloud-Instanz mit installierter und aktivierter Collectives-App

• Ein App-Passwort für den Nextcloud-Benutzer

App-Passwort erzeugen

1. In Nextcloud einloggen → Einstellungen → Sicherheit

2. Unter "Geräte & Sitzungen" ein neues App-Passwort erzeugen (beliebiger Name, z.B. nextcloud-collectives-mcp)

3. Das generierte Passwort notieren (wird nur einmal angezeigt)

Installation & Nutzung

Methode A: Direkt über npx ausführen (Empfohlen)

Es ist kein manuelles Klonen oder Bauen nötig. Der MCP-Server kann direkt über npx von GitHub gestartet werden. Fügen Sie dazu einfach den folgenden Eintrag in Ihrer MCP-Client-Konfiguration (z.B. claude_desktop_config.json oder per claude mcp add) hinzu:

{
  "mcpServers": {
    "nextcloud-collectives": {
      "command": "npx",
      "args": ["-y", "github:BamButz/nextcloud-collectives-mcp"],
      "env": {
        "NEXTCLOUD_BASE_URL": "https://cloud.example.com",
        "NEXTCLOUD_USERNAME": "alice",
        "NEXTCLOUD_APP_PASSWORD": "xxxxx-xxxxx-xxxxx-xxxxx-xxxxx"
      }
    }
  }
}

Hinweis: Beim Start lädt npx das Repository herunter und baut es automatisch über das prepare-Skript im Hintergrund.

Methode B: Manuelle lokale Installation (z.B. für Entwicklung)

1. Repository klonen und in den Ordner wechseln.

2. Abhängigkeiten installieren und bauen:

   npm install
   npm run build

3. In der MCP-Server-Konfiguration eintragen:

   {
     "mcpServers": {
       "nextcloud-collectives-local": {
         "command": "node",
         "args": ["/pfad/zu/nextcloud-collectives-mcp/dist/index.js"],
         "env": {
           "NEXTCLOUD_BASE_URL": "https://cloud.example.com",
           "NEXTCLOUD_USERNAME": "alice",
           "NEXTCLOUD_APP_PASSWORD": "xxxxx-xxxxx-xxxxx-xxxxx-xxxxx"
         }
       }
     }
   }

Verfügbare Tools

Collectives

• list_collectives — alle sichtbaren Collectives auflisten

• create_collective — neues Collective anlegen

• delete_collective — Collective in den Papierkorb verschieben

Seiten

• list_pages — vollständigen Seitenbaum eines Collectives auflisten (nur Metadaten)

• get_page — Metadaten und Markdown-Inhalt einer Seite abrufen

• create_page — neue Seite unter einer übergeordneten Seite anlegen

• update_page_content — Markdown-Inhalt einer Seite ersetzen

• rename_page — Seite umbenennen

• move_page — Seite zu einer neuen übergeordneten Seite verschieben

• delete_page — Seite in den Papierkorb verschieben

Tags

• list_tags — alle Tags eines Collectives auflisten

• create_tag — neuen Tag anlegen

• add_tag_to_page — Tag an eine Seite anhängen

• remove_tag_from_page — Tag von einer Seite entfernen

Entwicklung

npm test          # Tests einmalig ausführen
npm run test:watch
npm run coverage   # Tests + Code-Coverage-Bericht (Text + HTML unter coverage/index.html)
npm run typecheck
npm run dev        # Server direkt mit tsx starten (liest Env-Vars aus der Shell)

Implementierungshinweis

Dieses Projekt wurde vollständig mithilfe von Künstlicher Intelligenz (Gemini 3.5 (Flash)) von Google DeepMind im Rahmen eines agentischen Coding-Workflows implementiert und getestet.