caldav-mcp

Geben Sie Ihrem KI-Assistenten einen Kalender. Ein MCP-Server, der Lese-/Schreibzugriff auf jeden CalDAV-kompatiblen Kalender bietet – Nextcloud, Radicale, Baikal, ownCloud, iCloud, Fastmail und mehr – über 14 zweckgerichtete Tools.

Warum caldav-mcp?

Related MCP server: mcp-labrat

Wo es glänzt

• KI-gestützte Kalenderverwaltung – Lassen Sie Claude, Codex oder einen beliebigen MCP-Client Ereignisse über natürliche Sprache erstellen, aktualisieren, suchen und löschen.

• Multi-Tenant-Zugriff – Senden Sie pro Anfrage unterschiedliche X-Caldav-*-Header, um von einer einzelnen Serverinstanz aus auf verschiedene CalDAV-Konten zuzugreifen.

• Self-hosted Kalenderautomatisierung – Kombinierbar mit Ihrem bestehenden Nextcloud-, Radicale- oder Baikal-Server. Keine Cloud-Abhängigkeit.

• Enterprise-/Team-Bereitstellungen – Zentralisiert, zustandslos, containerisiert. Hinter einem Reverse-Proxy bereitstellen, horizontal skalieren, Anmeldedaten ohne Ausfallzeiten rotieren.

Schnellstart

# 1. Clone the repo
git clone https://git.gelse.net/werner/caldav-mcp.git && cd caldav-mcp

# 2. Create your .env file
cp .env.example .env
# Edit .env — at minimum set CALDAV_MCP_API_KEY, CALDAV_URL, CALDAV_USERNAME, CALDAV_PASSWORD

# 3. Launch
docker compose up -d

# 4. Verify
curl -s http://localhost:8600/mcp \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "X-Caldav-Url: https://cloud.example.com/remote.php/dav/calendars/user/" \
  -H "X-Caldav-Username: user" \
  -H "X-Caldav-Password: app-password" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1"}}}'

Der Server ist nun unter http://localhost:8600/mcp erreichbar (Streamable HTTP).

Tools

Der Server stellt 14 MCP-Tools in drei Kategorien bereit.

Abfragen (nur lesen)

Mutationen (schreiben)

Teilnehmer

Bereitstellung

Docker

Das Projekt enthält ein mehrstufiges Dockerfile:

1. Builder-Stufe – installiert Python-Abhängigkeiten aus requirements.txt in ein sauberes Präfix.

2. Runtime-Stufe – kopiert vorgebaute Pakete in ein minimales Alpine-Image, läuft als Nicht-Root-Benutzer app, exponiert Port 8080.

docker build -t caldav-mcp:latest .
docker run -p 8600:8080 \
  -e CALDAV_MCP_API_KEY=YOUR_KEY \
  -e CALDAV_URL=https://cloud.example.com/remote.php/dav/calendars/user/ \
  -e CALDAV_USERNAME=user \
  -e CALDAV_PASSWORD=app-password \
  caldav-mcp:latest

Docker Compose

docker-compose.yaml bildet Host-Port 8600 auf Container-Port 8080 ab und liest Umgebungsvariablen aus einer lokalen .env-Datei:

services:
  caldav-mcp:
    build: .
    image: caldav-mcp:latest
    restart: unless-stopped
    ports:
      - "8600:8080"
    environment:
      CALDAV_MCP_API_KEY: "${CALDAV_MCP_API_KEY:-}"
      TZ: Europe/Vienna

docker compose up -d

Eine docker-compose.test.yaml ist ebenfalls für Integrationstests verfügbar – sie enthält einen Radicale-CalDAV-Server.

TLS / HTTPS

Der Server unterstützt integriertes TLS ohne Reverse-Proxy. Setzen Sie diese Umgebungsvariablen, um HTTPS direkt zu aktivieren:

CALDAV_MCP_TLS_CERT=/path/to/cert.pem
CALDAV_MCP_TLS_KEY=/path/to/key.pem
CALDAV_MCP_TLS_CA_BUNDLE=/path/to/ca.pem   # optional

Wenn TLS aktiviert ist, lauscht der Server auf HTTPS. Wenn nicht gesetzt, betreiben Sie ihn hinter einem Reverse-Proxy (Traefik, Caddy, nginx), der TLS terminiert.

Authentifizierung

Zwei unabhängige Ebenen – beide optional, aber empfohlen.

Ebene 1: MCP-Endpunkt-Authentifizierung

Wenn CALDAV_MCP_API_KEY gesetzt ist, muss jede Anfrage an den /mcp-Endpunkt eines der folgenden enthalten:

• Authorization: Bearer <token>

• X-Api-Key: <token>

Der Token wird mit Konstantzeit-Vergleich geprüft, um Timing-Seitenkanalangriffe zu verhindern. Fehlgeschlagene Versuche werden pro Client-IP mit einem Sliding-Window-Rate-Limiter mit exponentiellem Backoff verfolgt.

Wenn CALDAV_MCP_API_KEY nicht gesetzt ist, ist der Endpunkt offen – setzen Sie ihn ohne Authentifizierung nicht dem öffentlichen Internet aus.

Ebene 2: CalDAV-Anmeldedaten

CalDAV-Anmeldedaten werden pro Anfrage aufgelöst:

1. HTTP-Header (bevorzugt): X-Caldav-Url, X-Caldav-Username, X-Caldav-Password

2. Umgebungsvariablen (Fallback): CALDAV_URL, CALDAV_USERNAME, CALDAV_PASSWORD

HTTP-Header haben Vorrang. Dies ermöglicht Multi-Tenant-Nutzung – verschiedene Clients können ohne Serverneustart auf verschiedene CalDAV-Konten zugreifen.

Konfiguration

Die gesamte Konfiguration erfolgt über Umgebungsvariablen, die beim Start mit Pydantic validiert werden.

Server

CalDAV

Rate Limiting

TLS

Protokollierung

Sicherheit

• Setzen Sie den Server hinter einen Reverse-Proxy, der TLS terminiert, oder aktivieren Sie integriertes TLS.

• Setzen Sie einen starken CALDAV_MCP_API_KEY.

• Beschränken Sie den Zugriff auf Netzwerk-/Firewall-Ebene auf vertrauenswürdige Hosts oder ein VPN.

• Bevorzugen Sie die Bindung an 127.0.0.1, es sei denn, Sie benötigen explizit Remote-Zugriff.

• Platzieren Sie CalDAV-App-Passwörter niemals in öffentlichen Konfigurationen oder Logs.

Entwicklung

Befehle

make test           # Run unit tests
make test-integration  # Run integration tests (requires docker-compose.test.yaml)
make test-performance  # Run performance benchmarks
make lint           # Lint with ruff (check + format)
make typecheck      # Type check with mypy
make check          # All checks: lint + typecheck + deps-check + test
make deps-check     # Verify pyproject.toml and requirements.txt are in sync
make build          # Build Docker image

Projektstruktur

caldav-mcp/
├── server.py                 # Thin entrypoint, launches FastMCP HTTP server
├── caldav_mcp/               # Core package
│   ├── tools/                # MCP tool handlers
│   │   ├── queries.py        #   Read-only tools (7)
│   │   ├── mutations.py      #   Write tools (4)
│   │   └── attendees.py      #   Attendee management (3)
│   ├── auth.py               # Two-layer auth (API key + CalDAV creds)
│   ├── calendar.py           # CalDAV calendar selection & serialization
│   ├── client_cache.py       # Thread-safe LRU cache for DAVClient
│   ├── config.py             # Env var parsing, header constants
│   ├── config_schema.py      # Pydantic startup validation
│   ├── datetime_utils.py     # Date/time parsing, timezone helpers
│   ├── errors.py             # Typed exceptions, ToolResult dataclass
│   ├── event_builder.py      # Pure iCalendar VEVENT construction
│   ├── sanitizers.py         # Input sanitization, field length limits
│   ├── rate_limit.py         # Sliding-window rate limiter
│   ├── audit.py              # Structured JSON audit logging
│   ├── constants.py          # Shared string constants
│   └── types.py              # CalDAVClient Protocol definition
├── tests/                    # Unit, integration, performance
├── docs/                     # Architecture, API, contributing docs
├── Dockerfile                # Multi-stage Docker build
├── docker-compose.yaml       # Production compose
├── docker-compose.test.yaml  # Test compose with Radicale
├── requirements.txt          # Runtime dependencies (pinned)
├── pyproject.toml            # Dev config and dependencies
└── Makefile                  # Build/test shortcuts

Abhängigkeiten

Fehlerbehebung

FAQ

F: Kann ich dies mit mehreren CalDAV-Konten verwenden? A: Ja — senden Sie pro Anfrage unterschiedliche X-Caldav-Url- / X-Caldav-Username- / X-Caldav-Password-Header. Der Client-Cache verwendet (url, username) als Schlüssel.

F: Welche CalDAV-Server werden unterstützt? A: Jeder Server, der den CalDAV-Standard implementiert: Nextcloud, ownCloud, iCloud, Fastmail, Baikal, Radicale und andere.

F: Wird das API-Token sicher übertragen? A: Nur bei Verwendung von HTTPS. Aktivieren Sie integriertes TLS oder platzieren Sie den Server hinter einem TLS-terminierenden Reverse-Proxy.

F: Wie generiere ich ein CalDAV-App-Passwort? A: Hängt von Ihrem Anbieter ab. Nextcloud: Einstellungen → Sicherheit → App-Passwörter. iCloud: Verwenden Sie ein app-spezifisches Passwort von appleid.apple.com.

F: Kann ich dies über stdio anstelle von HTTP verwenden? A: Der aktuelle Server verwendet ausschließlich den Streamable-HTTP-Transport. Um stdio zu verwenden, ändern Sie server.py so, dass mcp.run() anstelle von mcp.run_http_async() aufgerufen wird.

Lizenz

MIT