A Model Context Protocol server that gives MCP clients access to iCloud Calendar
over CalDAV: list calendars, read, create, update, move and delete events. It works on Linux, macOS and Windows,
since it talks to iCloud directly instead of going through the macOS Calendar app.
iCloud Calendar over CalDAV: list, create, update, move and delete events. Optional read-only mode.
Sign in to appleid.apple.com, open Sign-In and Security, then
App-Specific Passwords.
Generate a password, for example named mcp-icloud-caldav.
The username is your Apple ID address, which is not necessarily an @icloud.com address.
An app-specific password gives access to iCloud CalDAV, CardDAV and IMAP: keep it out of version control and revoke
it if it leaks.
Installation
The package is published on PyPI as mcp-icloud-caldav. With uv, MCP clients can
start it directly, without a separate install step:
uvx mcp-icloud-caldav
uvx downloads the package into a cached, isolated environment on first use. To install it permanently instead:
uv tool install mcp-icloud-caldav (or pipx install mcp-icloud-caldav).
From source:
git clone https://github.com/Glob0x17/mcp-icloud-caldav.git mcp-icloud-caldav
cd mcp-icloud-caldav
uv sync --no-dev
uv run mcp-icloud-caldav
Use the absolute path of uvx (which uvx) if the client cannot find it: clients often start servers without your
shell PATH, which shows up as spawn uvx ENOENT. Usual locations:
Installed with
Path
The uv installer (Linux, macOS)
~/.local/bin/uvx
Homebrew on Apple silicon
/opt/homebrew/bin/uvx
Homebrew on Intel Macs
/usr/local/bin/uvx
The command and its argument are separate fields: the command is uvx (or its path) and mcp-icloud-caldav is an
argument. A config where the command is the single string "uvx mcp-icloud-caldav" fails with ENOENT, because
the client looks for a program with that exact name, space included.
Keeping the password out of the client config
Most clients store env values in clear text in their config file. A small wrapper that reads an env file avoids
that:
or, with the wrapper, "command": "/home/you/.local/bin/mcp-icloud-caldav-run" and no env. Quit Claude Desktop
completely and start it again after editing. On macOS, server logs are in
~/Library/Logs/Claude/mcp-server-icloud-calendar.log.
Claude Code
claude mcp add --scope user icloud-calendar \
-e [email protected] -e ICLOUD_PASSWORD=xxxx-xxxx-xxxx-xxxx \
-- uvx mcp-icloud-caldav
or, with the wrapper, claude mcp add --scope user icloud-calendar -- ~/.local/bin/mcp-icloud-caldav-run.
Do not quote what follows --: -- uvx mcp-icloud-caldav registers uvx as the command and mcp-icloud-caldav as
its argument, while -- "uvx mcp-icloud-caldav" registers one program name and fails with ENOENT. To fix an
existing entry, remove it with claude mcp remove icloud-calendar --scope user and add it again.
/mcp in a session shows the server state and its tools; claude mcp get icloud-calendar shows the registered
command and arguments.
Other clients
Any MCP client that can start a stdio server works: run uvx mcp-icloud-caldav with the environment variables above.
The server is also listed in the MCP Registry as
io.github.Glob0x17/mcp-icloud-caldav.
Behavior worth knowing
Times. Event times are written in UTC. A time with an offset (2030-01-07T09:30:00+01:00) is converted, and a
time without one is taken as the machine's local time. Times are shown back in the machine's timezone. All-day
events are written as dates, with the end date exclusive as the iCalendar standard requires.
Moving between calendars. iCloud refuses the same event UID in two calendars, so a move cannot be
"copy then delete". update_event with calendar_name uses a WebDAV MOVE, which is atomic on the server: if it
fails, the event stays where it was. A move without other changes keeps the original iCalendar data untouched.
Finding events. Listings fill an in-memory index (UID to URL) that lives as long as the server process.
Lookups then go straight to the event, falling back to the <calendar>/<UID>.ics URL iCloud uses for most
events, and only then to a scan of all calendars. iCloud does not support CalDAV UID searches.
Volume. iCloud returns any number of events per request. The practical limit is the client: many cap a tool
result at around 25,000 tokens, roughly 300 events in this server's output, so split long ranges.
Scope. Only calendars hosted on iCloud are visible. Exchange, Google or other accounts added to the Calendar
app on a device are not reachable through iCloud CalDAV, and neither are read-only subscribed (ICS) calendars.
Privacy and security
The only network destination is the configured CalDAV server; there is no telemetry.
The password never appears in logs, at any level, nor in the configuration object's repr.
Logs go to stderr only, since stdout carries the MCP protocol. Event contents (titles, notes) are logged only at
DEBUG or below; at INFO, only identifiers. Some clients save server stderr to disk, so keep DEBUG for
troubleshooting.
Dependencies are locked in uv.lock and resolved from the official PyPI index only.
Troubleshooting
Symptom
Likely cause
401 Unauthorized
Regular Apple ID password instead of an app-specific one, or a revoked one
spawn uvx ENOENT or ENOENT
uvx is not on the client's PATH (use its absolute path), or the command and its argument were registered as one string (see Client setup)
No events returned
Wrong date range, an event in a non-iCloud or subscribed calendar, or a timezone mix-up
Server does not respond
Something writes to stdout and breaks the stdio protocol
Calendar 'X' not found
Calendar names are case-sensitive: check list_calendars
debug_calendar_connection and MCP_ICAL_LOG_LEVEL=DEBUG help narrow things down.
Development
uv sync
uv run pytest -m "not integration" # unit tests, CalDAV client mocked, no network
uv run ruff check .
Integration tests run against a real account, read-only, and are skipped unless credentials are set:
ICLOUD_USERNAME=... ICLOUD_PASSWORD=... uv run pytest -m integration
Project layout:
mcp_icloud_caldav/
├── server.py # MCP server, tool registration, logging setup
├── caldav_client.py # CalDAV access: search, create, update, move, delete, event index
├── ical.py # Thin calendar manager used by the server
├── models.py # Event and request models, iCalendar parsing
└── config.py # Configuration loading
tests/ # Unit tests
tests/integration/ # Read-only tests against a real account
Changes in this fork
0.2.1: documentation only (uvx locations, ENOENT causes, client paths on macOS).
0.2.0, compared with zwrong/iCalendar 0.1.0:
Dependencies. Lockfile regenerated from the official PyPI index (it resolved packages through a third-party
mirror over plain HTTP). Upgrade to mcp 2.x (FastMCP became MCPServer) and caldav 3.x; the original code no
longer starts against current releases.
Configuration. Environment variables, MCP_ICAL_CONFIG, read-only mode, configurable log level, no event
contents in logs above DEBUG.
Fixes.
Creating an event with a timezone offset failed (Unable to guess TZID); all-day events and recurrence end
dates were written incorrectly.
Alarms were never read back.
Updating an event without a location, notes or URL failed; changing its time produced invalid iCalendar data.
Moving an event deleted it before saving the copy, so a failed save lost it.
New events got a UID containing spaces and the machine's hostname.
Behavior. Events sorted by start time, compact output without empty fields, in-memory event index.
Tests. Unit tests for configuration, read-only mode, logging, iCalendar output, moves and lookups.
Packaging. Published on PyPI as mcp-icloud-caldav and listed in the MCP Registry. The Python package and the
command are renamed from mcp_ical / mcp-ical, which clashed with the original macOS project. The unused
mcp[cli] extra was dropped.
Noch keine Tool-Liste. Remote-Server erhalten eine nach dem ersten Health-Check.
FAQ
Fragen
Wie installiere ich ICloud Calendar (CalDAV)?
Kopieren Sie auf dieser Seite die stdio-Konfiguration für Cursor, Claude Desktop, Claude Code oder VS Code. Sie nutzt die Installation des Herausgebers, keinen PlugMCP-Proxy.
Benötigt ICloud Calendar (CalDAV) einen API-Schlüssel?
Der Herausgeber nennt diese Umgebungsvariablen: ICLOUD_USERNAME, ICLOUD_PASSWORD, MCP_ICAL_READ_ONLY, MCP_ICAL_LOG_LEVEL.
Welchen Transport verwendet ICloud Calendar (CalDAV)?
ICloud Calendar (CalDAV) läuft lokal über stdio.
Wann wurde ICloud Calendar (CalDAV) zuletzt geprüft?
Zuletzt geprüft: 2026-11-09. iCloud Calendar over CalDAV: list, create, update, move and delete events. Optional read-only mode.