nc-mcp

Ein Model Context Protocol-Server für Nextcloud. Verbindet LLM-Agenten (z.B. Mistral Le Chat, Claude, pi) mit deiner Nextcloud:

Architektur

LLM-Agent (Mistral Le Chat, ...)          dein Rechner (z.B. pi/Claude Desktop, stdio-fähig)
        │                                          │
        └──────────── HTTPS + Bearer-Token ────────┘
                        │
              Apache-Reverse-Proxy (Subdomain, TLS)
                        │
              nc-mcp (Docker, Streamable HTTP)
                        │
              Nextcloud APIs (OCS / WebDAV / CalDAV / CardDAV)
                        │
                Nextcloud (App-Passwort)

• Transport: Streamable HTTP (/mcp) — funktioniert mit Mistral Le Chat („MCP Connectors") und jedem modernen MCP-Client.

• Auth (Client → MCP-Server): statischer Bearer-Token (MCP_TOKEN).

• Auth (MCP-Server → Nextcloud): App-Passwort (NC_APP_PASSWORD) — keine Weitergabe des echten Passworts, jederzeit widerrufbar.

Related MCP server: nextcloud-agent

Setup

1. App-Passwort erstellen

In Nextcloud: Einstellungen → Sicherheit → Geräte & Sitzungen → „Neues App-Passwort" (Name z.B. nc-mcp). Berechtigungen sind API-weit; das Passwort lässt sich dort jederzeit widerrufen.

2. Konfiguration

cp .env.example .env
# Werte eintragen:
#   NC_URL, NC_USERNAME, NC_APP_PASSWORD
#   MCP_TOKEN=$(openssl rand -hex 32)

3. Docker

docker compose up -d --build
docker compose logs -f

Der Server lauscht auf 127.0.0.1:8010 (nur lokal!). Nach außen wird er über einen Reverse-Proxy mit TLS freigegeben.

4. Reverse-Proxy (Apache-Beispiel)

<VirtualHost *:443>
    ServerName nc-mcp.example.com
    SSLEngine on
    SSLCertificateFile /etc/letsencrypt/live/nc-mcp.example.com/fullchain.pem
    SSLCertificateKeyFile /etc/letsencrypt/live/nc-mcp.example.com/privkey.pem
    AllowEncodedSlashes NoDecode
    ProxyPreserveHost On
    ProxyPass / http://127.0.0.1:8010/ timeout=300
    ProxyPassReverse / http://127.0.0.1:8010/
    RequestHeader set X-Forwarded-Proto "https"
</VirtualHost>

Caddy-Beispiel:

nc-mcp.example.com {
    reverse_proxy 127.0.0.1:8010
}

5. Mistral Le Chat verbinden

In Le Chat: Einstellungen → Connectors → MCP-Server hinzufügen

• URL: https://nc-mcp.example.com/mcp

• Bearer-Token: dein MCP_TOKEN

6. Prüfen

curl -s https://nc-mcp.example.com/mcp \
  -H "Authorization: Bearer $MCP_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
# → sollte die Tool-Liste zurückgeben; ohne Token: 401

Lokale Entwicklung (ohne Docker)

uv venv && uv pip install -e . pytest pytest-asyncio
pytest                    # Unit-Tests (offline)
NC_URL=... NC_USERNAME=... NC_APP_PASSWORD=... python scripts/smoke_test.py
uvicorn nc_mcp.app:app --port 8010

Tools im Detail

Alle Tools sind bewusst klein und LLM-freundlich (JSON in, JSON out):

• Files: files_list, files_read, files_write, files_mkdir, files_move, files_copy, files_delete, files_search

• Notes: notes_list, notes_get, notes_create, notes_update, notes_delete

• Calendar: calendar_list, calendar_events_list, calendar_event_create, calendar_event_update, calendar_event_delete, calendar_event_delete_series — Serientermine werden serverseitig expandiert (RFC 4791 CALDAV:expand): calendar_events_list liefert die tatsächlichen Folge-Termine im Zeitraum, nicht das Basisdatum der Wiederholungsregel.

• Tasks: tasks_lists, tasks_list, task_create, task_complete, task_delete

• Contacts: contacts_addressbooks_list, contacts_list, contact_create, contact_delete

• Talk: talk_rooms_list, talk_send_message, talk_read_messages

• Mail: mail_accounts_list, mail_mailboxes_list, mail_messages_list, mail_message_get, mail_send (benötigt die Mail-App mit eingerichtetem Postfach)

Datumsangaben sind ISO-Format (2025-12-24T18:00:00+01:00); ohne Offset gilt NC_DEFAULT_TZ (Default: Europe/Berlin), reine Datumsangaben erzeugen Ganztages-Termine.

Sicherheit

• Kein Nextcloud-Passwort im Spiel — nur ein widerrufbares App-Passwort.

• Der MCP-Server bindet lokal; TLS/Bearer kommen vom Reverse-Proxy-Setup.

• .env ist in .gitignore — niemals committen.

• files_delete verschiebt nur in den Nextcloud-Papierkorb (wiederherstellbar).

• Einschränkungen des App-Passworts (z.B. nur Lesen) werden von Nextcloud erzwungen — der Server hat keine eigenen Rechte darüber hinaus.

Bekannte Eigenheiten

• Talk-Räume: Manche Apache-Setups (Rewrite-Regeln) brechen den Plural- Endpunkt /ocs/.../api/v4/rooms mit OCS-Code 998. nc-mcp erkennt das und fällt automatisch auf /room (Singular) zurück. Übersteuern via NC_TALK_ROOMS_PATH.

• CardDAV-Pfad: Nextcloud liegt Adressbücher unter /remote.php/dav/addressbooks/users/<user>/ (mit users-Segment).

License

MIT — siehe LICENSE.