icloud-calendar-mcp
Allows an agent to read, create, update, and delete events — including recurring events — on iCloud calendars, with support for listing calendars, retrieving event details, and modifying or removing individual occurrences or entire series.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@icloud-calendar-mcp What events do I have on my Home calendar tomorrow?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
icloud-calendar-mcp
An MCP server that lets an agent read, publish, edit and delete events — including repeating ones — on iCloud calendars.
Apple ships no public REST API for iCloud Calendar, so this speaks CalDAV
against https://caldav.icloud.com using the caldav
and icalendar libraries.
Tools
Tool | Input | Output |
| — |
|
|
|
|
|
|
|
|
| The event; for a series also |
|
| The updated event and its |
|
| What was |
list_calendars exists because the other tools need an exact calendar name and
iCloud names are whatever the user typed in the Calendar app. Name matching is
case-insensitive and falls back to a unique substring match; an ambiguous or
unknown name comes back as an error listing the real calendars.
Related MCP server: icloud-mcp
Setup
1. Generate an app-specific password
Go to appleid.apple.com → Sign-In and Security →
App-Specific Passwords. You will get something shaped abcd-efgh-ijkl-mnop.
A normal Apple ID password cannot authenticate against iCloud CalDAV while two-factor authentication is switched on, and it is switched on for every modern Apple account. This is the single most common reason the tool fails to connect.
2. Install and configure
You need uv; it fetches Python 3.12+ for you if necessary.
git clone https://github.com/glowpotion/icloud-calendar-mcp.git
cd icloud-calendar-mcp
cp .env.example .env # then fill it in
uv syncVariable | Required | Default | Purpose |
| yes | — | Full iCloud email address |
| yes | — | App-specific password |
| no |
| IANA name used for input times with no offset, and for rendering times back |
| no |
| Override for a non-iCloud CalDAV server |
3. Verify the connection
set -a && source .env && set +a
uv run icloud-calendar-mcp --checkThis prints the calendars it can see and exits, so credential problems surface before you wire anything up:
OK: connected to https://caldav.icloud.com as you@icloud.com
Default timezone: Europe/London
3 calendar(s):
- Home
- Work
- Family4. Register with the agent
By default the server speaks MCP over stdio, run on the same machine as the
client (to host it on another machine, see Running on a Raspberry Pi).
Replace /path/to/icloud-calendar-mcp below with the directory you cloned
into. For Claude Code:
claude mcp add icloud-calendar \
--env ICLOUD_USERNAME=you@icloud.com \
--env ICLOUD_APP_PASSWORD=abcd-efgh-ijkl-mnop \
--env CALDAV_DEFAULT_TIMEZONE=Europe/London \
-- uv --directory /path/to/icloud-calendar-mcp run icloud-calendar-mcpOr, as raw config for any host that takes the standard mcpServers shape:
{
"mcpServers": {
"icloud-calendar": {
"command": "uv",
"args": ["--directory", "/path/to/icloud-calendar-mcp", "run", "icloud-calendar-mcp"],
"env": {
"ICLOUD_USERNAME": "you@icloud.com",
"ICLOUD_APP_PASSWORD": "abcd-efgh-ijkl-mnop",
"CALDAV_DEFAULT_TIMEZONE": "Europe/London"
}
}
}
}Hermes Agent
Hermes Agent reads MCP servers from
mcp_servers in ~/.hermes/config.yaml. It gives a stdio server only the
environment variables listed under its env, so the credentials have to be
listed there. Keep the values themselves in ~/.hermes/.env:
# ~/.hermes/.env
ICLOUD_USERNAME=you@icloud.com
ICLOUD_APP_PASSWORD=abcd-efgh-ijkl-mnopThen add one of these to ~/.hermes/config.yaml.
From a local checkout (if Hermes can't find uv, use the full path that
command -v uv prints):
mcp_servers:
icloud_calendar:
command: "uv"
args: ["--directory", "/path/to/icloud-calendar-mcp", "run", "icloud-calendar-mcp"]
env:
ICLOUD_USERNAME: "${ICLOUD_USERNAME}"
ICLOUD_APP_PASSWORD: "${ICLOUD_APP_PASSWORD}"
CALDAV_DEFAULT_TIMEZONE: "Europe/London"With Docker, and nothing to install:
mcp_servers:
icloud_calendar:
command: "docker"
args: ["run", "-i", "--rm",
"-e", "ICLOUD_USERNAME", "-e", "ICLOUD_APP_PASSWORD", "-e", "CALDAV_DEFAULT_TIMEZONE",
"ghcr.io/glowpotion/icloud-calendar-mcp:latest"]
env:
ICLOUD_USERNAME: "${ICLOUD_USERNAME}"
ICLOUD_APP_PASSWORD: "${ICLOUD_APP_PASSWORD}"
CALDAV_DEFAULT_TIMEZONE: "Europe/London"Over HTTP, to an always-on server (the Pi service
or Docker Compose), with
ICLOUD_CALENDAR_MCP_TOKEN=<token> added to ~/.hermes/.env:
mcp_servers:
icloud_calendar:
url: "http://127.0.0.1:8765/mcp"
headers:
Authorization: "Bearer ${ICLOUD_CALENDAR_MCP_TOKEN}"Check the connection with hermes mcp test icloud_calendar; it should list
six tools. Then run /reload-mcp in an open chat, or start a new one. The
tools show up as mcp__icloud_calendar__list_events and so on.
To give the agent read access only, add a filter to the server entry:
tools:
include: [list_calendars, list_events, get_event]Running with Docker
A multi-arch image (amd64 and arm64, so a Raspberry Pi works too) is published
as ghcr.io/glowpotion/icloud-calendar-mcp. To build it yourself instead, run
docker build -t icloud-calendar-mcp . in a checkout and use that name in the
commands below.
Check your credentials first, using a .env file filled in from
.env.example:
docker run --rm --env-file .env ghcr.io/glowpotion/icloud-calendar-mcp --checkAs a stdio server
The agent starts a fresh container for each session and talks to it over
stdin/stdout, so -i is required. A bare -e NAME forwards that variable from
the agent's own environment, which keeps the password out of the command line.
For Claude Code:
claude mcp add icloud-calendar \
--env ICLOUD_USERNAME=you@icloud.com \
--env ICLOUD_APP_PASSWORD=abcd-efgh-ijkl-mnop \
--env CALDAV_DEFAULT_TIMEZONE=Europe/London \
-- docker run -i --rm -e ICLOUD_USERNAME -e ICLOUD_APP_PASSWORD \
-e CALDAV_DEFAULT_TIMEZONE ghcr.io/glowpotion/icloud-calendar-mcpAlways on, over HTTP
docker-compose.yml runs the streamable-HTTP server with
a restart policy, a health check and a read-only filesystem:
cp .env.example .env # fill in your credentials
echo "MCP_AUTH_TOKEN=$(openssl rand -hex 32)" >> .env
docker compose up -dIt listens on http://127.0.0.1:8765/mcp on this machine only. Connect with the
header Authorization: Bearer <MCP_AUTH_TOKEN>, just as for the
Pi service. To open it to your network, change
the port mapping to "8765:8765"; the security notes for the Pi apply. Use
docker compose logs -f for logs, and
docker compose pull && docker compose up -d to update.
Running on a Raspberry Pi
The same server can run as an always-on service on a Pi (or any systemd Linux
box), speaking MCP's streamable-HTTP transport and guarded by a bearer token.
By default it listens on 127.0.0.1 only, for an agent harness running on the
Pi itself; --lan opens it to your home network or Tailscale instead.
Requirements on the Pi: 64-bit Raspberry Pi OS (Bookworm or later),
SSH access from your machine, rsync, and uv:
ssh pi@raspberrypi.local 'curl -LsSf https://astral.sh/uv/install.sh | sh'Deploy from this directory on your machine:
deploy/deploy.sh pi@raspberrypi.local # agent on the Pi itself
deploy/deploy.sh --lan pi@raspberrypi.local # clients elsewhere on the networkThat copies the project to ~/icloud-calendar-mcp on the Pi (never .git or
.env) and runs deploy/install.sh there, which:
installs the dependencies into a local
.venvwithuv sync --frozen;on the first run, creates
/etc/icloud-calendar-mcp.env(root-only, mode 600) from your local.env— sent once and then deleted on the Pi — or by prompting if you have none, and generates a randomMCP_AUTH_TOKEN;checks the iCloud credentials with
--check;installs and starts a hardened
icloud-calendar-mcpsystemd service on port 8765, and prints the URL and token to give your agent.
Run the same command again to deploy an update; the configuration is kept.
--lan only matters on the first install; to switch afterwards, change
MCP_HOST in the env file (127.0.0.1 or 0.0.0.0) and restart.
Connect the agent. Any MCP client that supports streamable HTTP needs two
things: the URL http://127.0.0.1:8765/mcp (or http://raspberrypi.local:8765/mcp
with --lan) and the header Authorization: Bearer <token>. For Claude Code:
claude mcp add --transport http icloud-calendar http://127.0.0.1:8765/mcp \
--header "Authorization: Bearer <token>"If your harness can only launch local commands, skip the service entirely and
have it run ~/icloud-calendar-mcp/.venv/bin/icloud-calendar-mcp over stdio,
passing ICLOUD_USERNAME, ICLOUD_APP_PASSWORD and CALDAV_DEFAULT_TIMEZONE
in its environment.
For clients that only launch local commands (such as Claude Desktop's
mcpServers config), bridge with
mcp-remote:
{
"mcpServers": {
"icloud-calendar": {
"command": "npx",
"args": ["-y", "mcp-remote", "http://raspberrypi.local:8765/mcp", "--allow-http",
"--header", "Authorization:Bearer <token>"]
}
}
}Day to day, on the Pi:
Task | Command |
Logs |
|
Status |
|
Change settings or rotate the token |
|
Health check (no token needed) |
|
Uninstall |
|
Security notes. On the default localhost bind nothing off the Pi can
connect, and the token keeps other local processes out. With --lan, traffic
is plain HTTP, so keep it on a network you trust or on Tailscale (which
encrypts it); don't port-forward it to the internet. Anyone holding the token
can read and change your calendars. To listen only on
the tailnet, set MCP_HOST to the Pi's Tailscale IP. MCP_ALLOWED_HOSTS
optionally restricts accepted Host headers as a DNS-rebinding defence. The
server refuses to bind beyond loopback without a token of at least 32
characters.
You can also run HTTP mode by hand anywhere:
MCP_AUTH_TOKEN=$(openssl rand -hex 32) uv run icloud-calendar-mcp --transport http --host 0.0.0.0How times are handled
iCloud is strict about time values, so the rules are deliberately narrow:
Input is ISO 8601.
2026-07-01T14:00:00+01:00is taken at its offset;2026-07-01T14:00:00has no offset and is read inCALDAV_DEFAULT_TIMEZONErather than being silently treated as UTC.On the wire, everything is converted to UTC and written as
...Z. That avoidsTZID=parameters, which would otherwise oblige us to ship a matchingVTIMEZONEcomponent or risk iCloud misplacing the event.Output is rendered back in
CALDAV_DEFAULT_TIMEZONEwith an explicit offset, so the caller never has to guess what a bare timestamp meant.All-day events: pass date-only values (
2026-08-03) for bothstart_timeandend_time.end_timeis the last day the event covers — the exclusiveDTENDthat iCalendar requires is added and stripped for you.
list_events defaults to a now → now + 30 days window and expands recurring
events, so each occurrence in range comes back separately (sharing a UID,
distinguished by recurrence_id). Ranges beyond 400 days are refused rather
than asking the server to expand an unbounded number of recurrences.
Editing and deleting
update_event only touches the fields you pass. An empty string clears
description or location. Moving only start_time keeps the duration; moving
only end_time keeps the start. Switching between all-day and timed needs both.
Edits are made to the stored iCalendar data in place, so alarms, attendees and
Apple's own X-APPLE-* properties survive, and SEQUENCE is bumped.
iCloud refuses CalDAV's search-by-UID (HTTP 412), so events are found by
fetching <uid>.ics directly — the name both iCloud and this server use — and,
failing that, by scanning the calendar.
Recurring events
recurrence takes an iCalendar
RRULE,
with or without the RRULE: prefix:
Want |
|
Every Monday and Wednesday |
|
Ten working days |
|
Fortnightly |
|
First of every month until the end of 2027 |
|
start_time/end_timedescribe the first occurrence, which must itself match the rule — a Tuesday start withBYDAY=MOis refused rather than left to each client's interpretation.A date-only
UNTILon a timed series means "through the end of that day" and is converted to the UTC form RFC 5545 requires.Repeating timed events are the exception to the UTC rule above: they are written as
TZID=local times with aVTIMEZONE, so a 09:00 meeting stays at 09:00 when the clocks change. Events already pinned to a timezone (anything made in Apple Calendar) keep theirs when edited.
To act on one occurrence, pass its recurrence_id from list_events as
occurrence (a date alone also works when only one occurrence falls on it):
update_event(..., occurrence=...)changes just that occurrence.delete_event(..., occurrence=...)removes just that occurrence.delete_event(..., occurrence=..., and_following=true)ends the series before it.
Without occurrence, update_event changes the whole series and
delete_event removes it. When a series is moved, its individually changed and
deleted occurrences move with it; any that no longer land on the new rule are
dropped and counted in removed_exceptions. recurrence="" turns a series
back into a single event.
Errors
Tool calls return {"status": "error", "error": "..."} rather than raising, so
the agent can read the problem and correct itself. Messages name the specific
cause — a missing env var, an unparseable timestamp, an unknown calendar (with
the available names listed), an unknown event_id, an occurrence that is not
part of the series, an RRULE that does not fit the start, a read-only calendar,
or rejected credentials.
Warnings
A successful call can still carry a warnings list when something worked but
not quite as asked, or had a side effect the user should hear about:
the event has attendees — this tool never sends invitations, updates or cancellations, and edits to someone else's meeting can be overwritten by the organizer;
a fixed offset (
-04:00) given for a repeating event was anchored to a named timezone, so occurrences follow that zone's daylight saving;editing a series discarded exceptions that no longer fit, or left occurrences with their own time, title, description or location unchanged (named by
recurrence_id, so they can be updated individually);changing the location removed Apple's map pin;
the server would not expand repeating events, so
list_eventsshows each series once;the event is an invitation to a single occurrence, or uses
EXRULE.
Not supported: "this and all following" edits (end the series with
delete_event(..., and_following=true) and create a new one), managing
attendees, and reminders/tasks.
Development
uv run pytestThe suite covers calendar-name resolution, timezone conversion in both
directions, all-day round-tripping, range validation, the recurrence-expansion
fallback for servers that reject expand, event lookup, partial updates,
recurring series (DST, per-occurrence edits and deletes, truncation, moving a
series with its exceptions), and the MCP tool schemas. It uses a
fake CalDAV calendar, so nothing touches the network.
Layout
src/icloud_calendar_mcp/
server.py MCP tool definitions and CLI entry point
http_app.py Streamable-HTTP transport with bearer-token auth
calendar_client.py CalDAV connection, calendar and event lookup, read/write/delete
recurrence.py RRULE validation and occurrence matching
config.py Environment configuration
timeutil.py ISO 8601 parsing and normalisation
Dockerfile Container image (stdio by default)
docker-compose.yml Always-on HTTP server in Docker
deploy/
deploy.sh Copy to a Pi over SSH and install/update there
install.sh Install or update the systemd service (runs on the Pi)
icloud-calendar-mcp.service systemd unit templateICloudCalendarClient is importable on its own if you ever want the CalDAV
logic without the MCP layer.
License
Available Tools
6 toolscreate_eventCreate calendar eventA
Publish a new event to an iCloud calendar. Returns the created event's ID (its iCalendar UID). Times are ISO 8601; a value with no UTC offset is read in the configured default timezone. Give date-only values for both start_time and end_time to create an all-day event, where end_time is the last day it covers. To make it repeat, pass recurrence as an iCalendar RRULE, e.g. 'FREQ=WEEKLY;BYDAY=MO,WE', 'FREQ=DAILY;COUNT=10' or 'FREQ=MONTHLY;BYMONTHDAY=1;UNTIL=20271231'; start_time/end_time then describe the first occurrence, which must itself match the rule. Repeating timed events keep their local time across daylight-saving changes.
Inputs: end_time (required), start_time (required), event_title (required), calendar_name (required), +3 more. Returns: object
delete_eventDelete calendar eventA
Delete an event. Without occurrence this removes the event, or the whole series if it repeats. For a repeating event, set occurrence to an occurrence's recurrence_id from list_events to delete only that one, and add and_following=true to also delete every occurrence after it (the series then ends before it). Cancellations are not sent to attendees. Check warnings in the result.
Inputs: event_id (required), calendar_name (required), occurrence, and_following. Returns: object
get_eventGet calendar eventA
Fetch one event by its event_id. For a repeating event this is the series itself: its first occurrence, its recurrence rule, the excluded_occurrences that were deleted, and the modified_occurrences that were changed individually.
Inputs: event_id (required), calendar_name (required). Returns: object
list_calendarsList calendarsA
List the iCloud calendars available to the account, with their names and CalDAV URLs. Use this to discover the exact calendar_name that create_event and list_events expect.
Inputs: no named parameters. Returns: object
list_eventsList upcoming eventsA
Fetch events from an iCloud calendar within a time range. Defaults to the next 30 days when no range is given. Recurring events are expanded, so each occurrence in the range is returned separately. Ranges longer than 400 days are rejected.
Inputs: calendar_name (required), end_date, start_date. Returns: object
update_eventUpdate calendar eventA
Change an existing event. Only the fields you pass are changed; pass an empty string to clear description or location. Changing only start_time moves the event and keeps its duration. For a repeating event, leave occurrence out to change the whole series, or set it to an occurrence's recurrence_id from list_events to change just that one. recurrence (whole series only) replaces the RRULE; an empty string stops the event repeating, and an RRULE makes a one-off event repeat. Moving a series moves its individually changed and deleted occurrences with it; any that no longer fit the new rule are discarded and counted in removed_exceptions. Changing "this and all following" occurrences is not supported: end the series with delete_event(..., and_following=true) and create a new one. Invitations are not sent to attendees. Check warnings in the result.
Inputs: event_id (required), calendar_name (required), end_time, location, +5 more. Returns: object
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 6 tools
Each tool maps to a distinct resource and action: list_calendars handles calendar discovery, while create/get/update/delete_event and list_events cleanly separate single-event, bulk-listing, and write operations. Recurring-event behavior is described carefully so get_event and list_events are not confused.
All tool names follow a consistent snake_case verb_noun convention: list_calendars, create_event, get_event, update_event, delete_event, list_events. The only variation is singular vs. plural nouns, which is appropriate for single-resource vs. collection operations.
Six tools is well-scoped for a calendar integration: four event lifecycle operations plus calendar discovery and range-based event listing. Each tool has a clear purpose and none feel redundant.
Event CRUD is fully covered, including recurring-event exceptions and range queries, and calendar discovery exists to support event operations. Minor gaps remain, such as no calendar creation/update/delete and no attendee/invitation management, but the core scheduling workflow is complete.
Related MCP Connectors
Let your agent into iCloud Mail, calendar and contacts. It gets actions, never your password.
Let your AI agent read and act on your Mail, Calendar, Contacts and more. Works with iCloud.
Read, search and manage iCloud Mail, Calendar and Contacts from Claude and other MCP clients.
Calendar API for AI agents: events, availability, Google/Microsoft setup, scheduling, and iCal.
Related MCP Servers
- AlicenseAqualityDmaintenanceEnables Claude (or any MCP client) to read and write events on your iCloud calendars via CalDAV.519 npmMIT
- AlicenseNot gradedqualityBmaintenanceEnables calendar management with iCloud through CalDAV, allowing users to list, create, update, and delete events via a standardized API.243 npmMIT
- AlicenseNot gradedqualityDmaintenanceProvides AI calendar operators full iCloud Calendar access through CalDAV, with two-factor authentication and app-specific passwords.MIT
- AlicenseNot gradedqualityDmaintenanceEnables Claude to interact with iCloud Calendar through CalDAV, allowing users to list, search, create, update, and delete calendar events using natural language.243 npmMIT