calendar-mcp-server (calmcp)

By Erik Bitzek e.bitzek@mpi-susmat.de — licensed under PolyForm Noncommercial 1.0.0

A thin, privacy-respecting CalDAV toolkit that lets an LLM read and manage your calendars — safely. The intelligence lives in the LLM and a small set of skill prompts; the tool itself is a compact set of well-guarded primitives with dry-run writes, role gating, and an audit log.

Works with any CalDAV server (Kerio Connect, Apple iCloud, Nextcloud, Radicale, Fastmail, …). Exposes everything over the Model Context Protocol (MCP) so it plugs straight into Claude Desktop, Claude Code, and Cowork.

Status. Read commands (list_calendars, query_events, find_events, get_free_busy, export_ics) and write commands (create_event, update_event, move_event, delete_event — dry-run by default) are implemented, plus the MCP adapter and LLM skills. Google (via its own API) is deferred; see DESIGN.md.

Why this design

• No secrets in the repo. Passwords never live in the code, in calendars.yaml, or in environment variables — they're stored in your OS keyring (macOS Keychain, Windows Credential Manager, Linux Secret Service).
• Writes are safe by default. Every write is a --confirm-gated dry-run that prints a before/after diff first. Writing to a calendar you don't own needs a second --confirm-foreign gate. Every real write is appended to an audit log.
• Least privilege. A small YAML registry maps friendly calendar ids to accounts and a safety role (owner / writable / read-only).
• LLM-friendly. Ships with skill prompts (skills/) so an assistant can turn free-text dates into events, do bulk edits, and check overlaps.

Install

python3 -m venv .venv
source .venv/bin/activate
pip install -e ".[mcp]"      # add ,dev for the test/lint tools: ".[mcp,dev]"

Configure

cp calendars.example.yaml calendars.yaml   # git-ignored; NO secrets go in it
$EDITOR calendars.yaml

calendars.yaml only maps calendar ids → accounts → roles. Store each account's password in the OS keyring (with the keyring CLI, installed alongside calmcp):

keyring set calmcp/kerio_personal jdoe          # prompts for the password (hidden)

If no keyring backend is available (e.g. a headless box), calmcp prompts once at runtime and keeps the secret in memory only.

Example calendars.yaml

accounts:
  kerio_personal:
    type: caldav
    url: "https://caldav.example.de/caldav/users/example.de/jdoe"
    username: jdoe
    keyring_service: "calmcp/kerio_personal"
    verify_ssl: true

  icloud:
    type: caldav
    url: "https://caldav.icloud.com"
    username: "your-apple-id@example.com"
    keyring_service: "calmcp/icloud"      # Apple APP-SPECIFIC password

calendars:
  - id: me_personal            # you own this one
    account: kerio_personal
    role: owner

  - id: family                 # shared to you, read-only
    account: icloud
    name: "Family"
    role: read-only

defaults:
  write_calendar: me_personal
  timezone: Europe/Berlin

iCloud

iCloud is just another CalDAV account. Use the endpoint https://caldav.icloud.com and an app-specific password (generate one at appleid.apple.com; your Apple ID has 2FA):

keyring set calmcp/icloud your-apple-id@example.com   # paste the app-specific password

Command-line usage

calmcp is fully usable from the terminal — handy for testing before you wire it into an assistant.

# List configured calendars (with a reachability probe):
calmcp list_calendars
calmcp list_calendars --offline           # just print the registry, no network

# Query events in an (inclusive) date range:
calmcp query_events --from 2026-06-01 --to 2026-06-30
calmcp query_events --from 2026-06-01 --to 2026-06-30 --expand --json
calmcp query_events --from 2026-06-01 --to 2026-06-30 --calendars me_personal

# Search text, check free/busy, export to an .ics file:
calmcp find_events   --from 2026-06-01 --to 2026-12-31 --q "DFG"
calmcp get_free_busy --from 2026-06-14 --to 2026-06-21 --json
calmcp export_ics    --from 2026-06-01 --to 2026-06-30 --out june.ics

Writing events (safe by default)

Write commands print a dry-run diff and do nothing until you add --confirm:

# Preview (dry-run) — shows before/after, writes nothing:
calmcp create_event --calendar me_personal --summary "Dentist" \
    --start "2026-07-01 09:00" --end "2026-07-01 09:30"

# Actually create it:
calmcp create_event --calendar me_personal --summary "Dentist" \
    --start "2026-07-01 09:00" --end "2026-07-01 09:30" --confirm

calmcp update_event --calendar me_personal --uid <uid> --set location="Room 2" --confirm
calmcp move_event   --calendar me_personal --uid <uid> \
    --start "2026-07-01 10:00" --end "2026-07-01 10:30" --confirm
calmcp delete_event --calendar me_personal --uid <uid> --confirm

Writing to a calendar whose role isn't owner adds a warning and requires a second --confirm-foreign gate. Recurring writes take --scope this|all|thisAndFuture. Every real write is appended to an audit log (~/.local/state/calmcp/audit.jsonl on Linux/macOS).

Point calmcp at a non-default registry with --registry path/to/calendars.yaml or the CALMCP_REGISTRY environment variable.

Connect to Claude (MCP)

calmcp exposes these tools over MCP (stdio):

Tool	What it does
list_calendars	List configured calendars, roles, and reachability
query_events	List events in a date range (optionally expand recurrences)
find_events	Full-text search across calendars in a range
get_free_busy	Free/busy blocks for a range
export_ics	Export a range to iCalendar (.ics)
create_event	Create an event (dry-run unless confirmed)
update_event	Change fields on an event
move_event	Reschedule an event
delete_event	Delete an event

The MCP server finds its registry from $CALMCP_REGISTRY, falling back to ./calendars.yaml. Because your client launches the server from an arbitrary working directory, always set CALMCP_REGISTRY to an absolute path.

Claude Desktop

Edit your config file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

Add a calmcp server (use the absolute path to the calmcp-mcp binary inside your virtualenv):

{
  "mcpServers": {
    "calmcp": {
      "command": "/path/to/calendar-mcp-server/.venv/bin/calmcp-mcp",
      "env": {
        "CALMCP_REGISTRY": "/path/to/calendar-mcp-server/calendars.yaml"
      }
    }
  }
}

Restart Claude Desktop. You should see the calmcp tools available in a new chat.

Claude Code

claude mcp add calmcp \
  --env CALMCP_REGISTRY=/path/to/calendar-mcp-server/calendars.yaml \
  -- /path/to/calendar-mcp-server/.venv/bin/calmcp-mcp

Then check it with claude mcp list.

Skills

The prompts in skills/ (dates-to-events, bulk-edit, overlap-check) teach an assistant common calendar workflows on top of these tools. Point your assistant at that folder, or paste a skill into the conversation.

Develop

pip install -e ".[mcp,dev]"
ruff check .
mypy calmcp
pytest

Tests run against a local Radicale CalDAV fixture — no real credentials, and no network calls to any real provider.

License

Copyright © 2026 Erik Bitzek e.bitzek@mpi-susmat.de.

Released under the PolyForm Noncommercial License 1.0.0 — you're free to use, modify, and share it for any noncommercial purpose (personal projects, research, education, and other noncommercial organizations). Commercial use requires a separate license from the author. See LICENSE.md for the full terms.