Nextcloud CalDAV MCP Server

An MCP (Model Context Protocol) server that lets Claude create calendar events and tasks in Nextcloud via CalDAV.

Tools exposed:

Tool	Description
create_event	Writes a VEVENT into a Nextcloud Calendar
create_todo	Writes a VTODO into Nextcloud Tasks

Stack: Python 3 · mcp SDK 1.x · caldav · uvicorn · Tailscale Funnel (HTTPS)

---

Prerequisites

Install on the Proxmox host (Debian/Ubuntu):

apt update
apt install -y python3 python3-venv python3-pip git

No nginx, no certbot needed — Tailscale handles TLS automatically.

---

1 — Deploy the server files

# Files already live in /root/calendar_todo_mcp
# Copy the service file to systemd
mkdir -p /root/calendar_todo_mcp
cp server.py requirements.txt calendar_todo_mcp.service /root/calendar_todo_mcp/

---

2 — Python virtual environment

python3 -m venv /root/calendar_todo_mcp/venv
/root/calendar_todo_mcp/venv/bin/pip install --upgrade pip
/root/calendar_todo_mcp/venv/bin/pip install -r /root/calendar_todo_mcp/requirements.txt

---

3 — Configure .env

cp /root/calendar_todo_mcp/.env.example /root/calendar_todo_mcp/.env
nano /root/calendar_todo_mcp/.env       # or your preferred editor
chmod 600 /root/calendar_todo_mcp/.env

Required values to fill in:

Variable	Example	Notes
NEXTCLOUD_URL	https://cloud.example.com	No trailing slash
NEXTCLOUD_USER	youruser	Your login username
NEXTCLOUD_APP_PASSWORD	xxxx-xxxx-xxxx	See step below
CALENDAR_NAME	Personal	Exact display name in Nextcloud Calendar
TASKS_CALENDAR_NAME	Tasks	Exact display name in Nextcloud Tasks
OAUTH_CLIENT_ID	calendar-todo-client	Any identifier you choose
OAUTH_CLIENT_SECRET	(generated)	Run python3 -c "import secrets; print(secrets.token_urlsafe(32))"
RESOURCE_SERVER_URL	https://mymachine.tail-abc123.ts.net	Your Tailscale Funnel URL (see step 4)

Create a Nextcloud App Password

1. Log into Nextcloud → Settings → Security
2. Scroll to App passwords → enter a name (e.g. mcp-server) → click Generate new app password
3. Copy the password into NEXTCLOUD_APP_PASSWORD

---

4 — Tailscale einrichten

Tailscale installieren

curl -fsSL https://tailscale.com/install.sh | sh
tailscale up

Anmelden mit deinem Tailscale-Account im Browser, wenn der Link erscheint.

MagicDNS und HTTPS in der Tailscale-Konsole aktivieren

1. Öffne login.tailscale.com/admin/dns
2. MagicDNS aktivieren
3. HTTPS Certificates aktivieren

Funnel aktivieren (öffentlich erreichbar via HTTPS)

Tailscale Funnel macht den Server über das öffentliche Internet erreichbar — nötig, damit Claude.ai (Cloud) den MCP-Server erreichen kann.

Der mitgelieferte tailscale_funnel.service startet den Funnel automatisch beim Booten (siehe Schritt 5). Zum Testen vorab:

tailscale funnel 8000

Danach die URL deines Servers ermitteln:

tailscale funnel status
# Ausgabe z.B.: https://mymachine.tail-abc123.ts.net/ proxies to http://127.0.0.1:8000

Diesen HTTPS-Hostnamen (z.B. https://mymachine.tail-abc123.ts.net) als RESOURCE_SERVER_URL in die .env eintragen.

Nur im Tailnet (kein öffentlicher Zugriff)? Wenn Claude Desktop auf einem Gerät im selben Tailnet läuft, reicht tailscale serve 8000 statt funnel.

---

5 — Install and start the systemd services

Both service files need to be copied and enabled: the MCP server and the Tailscale Funnel.

# MCP server
cp /root/calendar_todo_mcp/calendar_todo_mcp.service \
   /etc/systemd/system/calendar-todo-mcp.service

# Tailscale Funnel (keeps the funnel running across reboots)
cp /root/calendar_todo_mcp/tailscale_funnel.service \
   /etc/systemd/system/tailscale-funnel-mcp.service

systemctl daemon-reload
systemctl enable --now calendar-todo-mcp
systemctl enable --now tailscale-funnel-mcp

# Verify both are running
systemctl status calendar-todo-mcp
systemctl status tailscale-funnel-mcp
journalctl -u calendar-todo-mcp -f

---

6 — Smoke test

Ersetze mymachine.tail-abc123.ts.net mit deiner tatsächlichen Tailscale-URL:

# OAuth-Metadaten-Endpoint — sollte JSON mit issuer/scopes zurückgeben
curl https://mymachine.tail-abc123.ts.net/.well-known/oauth-protected-resource \
  | python3 -m json.tool

# MCP-Endpoint ohne Token — sollte 401 zurückgeben
curl -s -o /dev/null -w "%{http_code}" \
     https://mymachine.tail-abc123.ts.net/mcp

---

7 — Connect Claude

MCP-Server in Claude.ai oder claude_desktop_config.json eintragen:

{
  "mcpServers": {
    "calendar-todo": {
      "url": "https://mymachine.tail-abc123.ts.net/mcp"
    }
  }
}

Claude startet beim ersten Verbinden automatisch den OAuth-Flow (Browser-Redirect). Danach ist keine weitere Konfiguration nötig.

Claude kann dann Dinge sagen wie:

"Trag mir einen Zahnarzttermin am 3. April um 10 Uhr für 45 Minuten ein" "Erinnerung: Bank anrufen — fällig morgen"

---

Operations

# View live logs
journalctl -u calendar-todo-mcp -f

# Restart after config changes
systemctl restart calendar-todo-mcp

# Stop / disable
systemctl stop calendar-todo-mcp
systemctl disable calendar-todo-mcp

---

Troubleshooting

Problem	What to check
401 Unauthorized	OAuth-Flow noch nicht abgeschlossen — Claude erneut verbinden und Autorisierung im Browser bestätigen
Calendar 'X' not found	The CALENDAR_NAME / TASKS_CALENDAR_NAME must match the exact display name in Nextcloud
CalDAV 401	App password entered correctly? User has CalDAV access enabled?
Connection refused	Is the service running? systemctl status calendar-todo-mcp
Tailscale 502 Bad Gateway	MCP server not running, or wrong PORT in .env
Funnel antwortet nicht	tailscale funnel status prüfen; ggf. tailscale funnel 8000 erneut ausführen
Tailscale HTTPS geht nicht	MagicDNS und HTTPS Certificates in der Tailscale-Admin-Console aktiviert?