Radicale CalDAV MCP Server

Ein Model Context Protocol (MCP)-Server, erstellt mit FastMCP bzw. dem offiziellen MCP Python SDK, der LLM-Agenten (wie z. B. Nous Hermes, Claude, OpenAI) mit einem selbst gehosteten Radicale CalDAV-Kalender und einer Aufgabenverwaltung verbindet.

Funktionen

📅 Kalendertermine (VEVENT)

• get_events: Termine in Datums-/Zeitbereichen abfragen, mit optionaler Stichwortsuche über Zusammenfassung, Beschreibung und Ort.

• get_free_busy_slots: Freie, nicht gebuchte Zeitfenster innerhalb konfigurierbarer Geschäftszeiten (z. B. 9:00–17:00 Uhr) in einer beliebigen IANA-Zeitzone berechnen.

• create_event: Neue Termine mit automatischer ISO-Validierung, Teilnehmereinladungen und Überlappungs-/Konflikterkennung planen.

• update_event: Vorhandene Termine anhand der UID ändern, ohne unberührte Felder zu überschreiben.

• delete_event: Termine anhand der UID entfernen.

📝 Aufgaben & To-Dos (VTODO)

• list_todos: Anstehende oder abgeschlossene Aufgaben abrufen, gefiltert nach Status (NEEDS-ACTION, COMPLETED, IN-PROCESS, CANCELLED, ALL).

• create_todo: Aufgaben mit Fälligkeitsdatum, Prioritätsstufen (1–9) und Beschreibungen erstellen.

• complete_todo: Aufgaben als abgeschlossen markieren, mit automatisch erzeugtem Abschluss-Zeitstempel.

🚀 Transporte & Bereitstellung

• STDIO-Transport: Standardtransport für die lokale Ausführung (z. B. Claude Desktop, lokale Agenten).

• SSE-Transport (Server-Sent Events): Über HTTP für entfernte, dauerhaft laufende Bereitstellungen (z. B. Coolify, Docker).

Related MCP server: caldav-mcp

Konfiguration

Konfigurieren Sie den Server über Umgebungsvariablen oder eine .env-Datei:

Lokaler Schnellstart

1. Installation

# Clone and enter directory
cd radicale-mcp-server

# Create virtual environment
python3 -m venv .venv
source .venv/bin/activate

# Install dependencies
pip install -r requirements.txt

2. Umgebung konfigurieren

Kopieren Sie .env.example nach .env und setzen Sie Ihre Zugangsdaten ein:

cp .env.example .env

3. Lokal ausführen

STDO-Modus (lokale Pipe)

python server.py --stdio

SSE-Modus (HTTP-Server)

python server.py --sse --host 0.0.0.0 --port 8000

4. Test-Client ausführen

# Test via STDIO
python test_client.py --mode stdio

# Test via SSE (when server is running)
python test_client.py --mode sse --sse-url http://localhost:8000/sse

5. Automatisierte Tests ausführen

pytest -v

Bereitstellung auf Coolify

Stellen Sie den MCP-Server ohne Konfiguration auf Coolify bereit:

1. Erstellen Sie in Coolify einen neuen Dienst: Docker Compose oder Dockerfile.

2. Verweisen Sie ihn auf dieses Repository oder fügen Sie die docker-compose.yml ein.

3. Setzen Sie die folgenden Umgebungsvariablen in der Coolify-Oberfläche:

   • RADICALE_BASE_URL=https://radicale.dubblu.app

   • RADICALE_USERNAME=mvela581

   • RADICALE_PASSWORD=your_password

   • RADICALE_CALENDAR_SLUG=seuspeptides

   • DEFAULT_TIMEZONE=America/New_York

   • MCP_TRANSPORT=sse

   • MCP_PORT=8000

4. Geben Sie Port 8000 über den Reverse-Proxy von Coolify mit Ihrer Domain frei (z. B. https://mcp-calendar.yourdomain.com).

5. Ihr SSE-Endpunkt ist erreichbar unter:

https://mcp-calendar.yourdomain.com/sse

LLM-Agenten-Integration (Nous Hermes / Claude Desktop)

Konfiguration für Claude Desktop

Fügen Sie Ihrer claude_desktop_config.json Folgendes hinzu:

Lokales STDIO:

{
  "mcpServers": {
    "radicale_calendar": {
      "command": "/path/to/radicale-mcp-server/.venv/bin/python",
      "args": ["/path/to/radicale-mcp-server/server.py", "--stdio"],
      "env": {
        "RADICALE_BASE_URL": "https://radicale.dubblu.app",
        "RADICALE_USERNAME": "mvela581",
        "RADICALE_PASSWORD": "your_password",
        "RADICALE_CALENDAR_SLUG": "seuspeptides",
        "DEFAULT_TIMEZONE": "America/New_York"
      }
    }
  }
}

Remote-SSE (Coolify):

{
  "mcpServers": {
    "radicale_calendar": {
      "url": "https://mcp-calendar.yourdomain.com/sse"
    }
  }
}

Nous-Hermes-Agenten-Integration

Die Tool-Definitionen werden automatisch aus Docstrings mit Typspezifikationen generiert. Beispiel für die Verwendung im Prompt:

{
  "name": "get_free_busy_slots",
  "arguments": {
    "start_date": "2026-08-26",
    "end_date": "2026-08-28",
    "slot_duration_minutes": 30,
    "working_hours_start": 9,
    "working_hours_end": 17,
    "timezone": "America/New_York"
  }
}

Lizenz

MIT