caldav CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Overview

caldav-mcp is a single-file Python MCP server (server.py, FastMCP over stdio) that gives Claude Desktop/Cowork/Code access to plain CalDAV calendars (SOGo, Nextcloud, Radicale, …) — the calendars not covered by the official Google/M365 connectors. It is the sibling of ../imap (imap-mcp) and deliberately mirrors its structure and safety model: server.py holds all tools, test_server.py the tests, install.py the Claude Desktop registration.

Commands

bash setup.sh                        # create .venv, install deps, register in Claude Desktop (idempotent)
.venv/bin/python server.py --check   # validate accounts.json + password resolution without starting the server
.venv/bin/python server.py --set-password "<account>"  # store a password in the OS keychain
.venv/bin/python test_server.py      # run tests (offline — no CalDAV server, no framework, plain asserts)

On Windows use .\setup.ps1 and .venv\Scripts\python.exe. There is no pytest/lint setup; the test file is a script that prints per-check status and ALL CHECKS PASSED.

Configuration lives in accounts.json (gitignored, credentials — never commit or print it). accounts.example.json is the template; install.py copies it on first setup and registers the server as caldav in Claude Desktop's config.

Architecture: config-level safety gating

As in imap-mcp, all guardrails live in accounts.json, not in prompts or tool descriptions, so they hold under prompt injection from event content. Every tool falls into one of two tiers, and any new tool must be gated the same way:

1. Read tools (list_accounts, list_calendars, search_events, get_event) — always allowed.
2. Write tools (create_event, update_event, cancel_event) — must call _require_writes(account) first, which raises PermissionError unless the account has "allow_writes": true. Deletion does not exist: cancel_event only sets STATUS:CANCELLED (reversible via cancelled=false); never add a real delete/.delete() call.
3. There is no send tier at all — events can never carry attendees (create_event/update_event deliberately have no attendee parameter), so the CalDAV server can never emit iTIP/iMIP invitation emails on our behalf. Do not add attendee support.