Skip to main content
Glama

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

list_calendars

—

calendars: name + CalDAV URL for each calendar on the account

create_event

calendar_name, event_title, start_time, end_time, description?, location?, recurrence?

status, event_id, plus the normalised times actually written

list_events

calendar_name, start_date?, end_date?

count and events[] — each with title, start_time, end_time, event_id, location, description, all_day, and recurrence_id for occurrences of a series

get_event

calendar_name, event_id

The event; for a series also recurrence, excluded_occurrences and modified_occurrences

update_event

calendar_name, event_id, any of event_title, start_time, end_time, description, location, recurrence; occurrence?

The updated event and its scope (event, series or occurrence)

delete_event

calendar_name, event_id, occurrence?, and_following?

What was deleted: event, series, occurrence or occurrence_and_following

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 sync

Variable

Required

Default

Purpose

ICLOUD_USERNAME

yes

—

Full iCloud email address

ICLOUD_APP_PASSWORD

yes

—

App-specific password

CALDAV_DEFAULT_TIMEZONE

no

UTC

IANA name used for input times with no offset, and for rendering times back

CALDAV_URL

no

https://caldav.icloud.com

Override for a non-iCloud CalDAV server

3. Verify the connection

set -a && source .env && set +a
uv run icloud-calendar-mcp --check

This 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
  - Family

4. 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-mcp

Or, 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-mnop

Then 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 --check

As 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-mcp

Always 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 -d

It 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 network

That copies the project to ~/icloud-calendar-mcp on the Pi (never .git or .env) and runs deploy/install.sh there, which:

  1. installs the dependencies into a local .venv with uv sync --frozen;

  2. 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 random MCP_AUTH_TOKEN;

  3. checks the iCloud credentials with --check;

  4. installs and starts a hardened icloud-calendar-mcp systemd 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

sudo journalctl -u icloud-calendar-mcp -f

Status

systemctl status icloud-calendar-mcp

Change settings or rotate the token

sudo nano /etc/icloud-calendar-mcp.env && sudo systemctl restart icloud-calendar-mcp

Health check (no token needed)

curl http://127.0.0.1:8765/healthz

Uninstall

sudo systemctl disable --now icloud-calendar-mcp && sudo rm /etc/systemd/system/icloud-calendar-mcp.service /etc/icloud-calendar-mcp.env && rm -rf ~/icloud-calendar-mcp

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.0

How 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:00 is taken at its offset; 2026-07-01T14:00:00 has no offset and is read in CALDAV_DEFAULT_TIMEZONE rather than being silently treated as UTC.

  • On the wire, everything is converted to UTC and written as ...Z. That avoids TZID= parameters, which would otherwise oblige us to ship a matching VTIMEZONE component or risk iCloud misplacing the event.

  • Output is rendered back in CALDAV_DEFAULT_TIMEZONE with 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 both start_time and end_time. end_time is the last day the event covers — the exclusive DTEND that 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

recurrence

Every Monday and Wednesday

FREQ=WEEKLY;BYDAY=MO,WE

Ten working days

FREQ=DAILY;BYDAY=MO,TU,WE,TH,FR;COUNT=10

Fortnightly

FREQ=WEEKLY;INTERVAL=2

First of every month until the end of 2027

FREQ=MONTHLY;BYMONTHDAY=1;UNTIL=20271231

  • start_time/end_time describe the first occurrence, which must itself match the rule — a Tuesday start with BYDAY=MO is refused rather than left to each client's interpretation.

  • A date-only UNTIL on 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 a VTIMEZONE, 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_events shows 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 pytest

The 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 template

ICloudCalendarClient is importable on its own if you ever want the CalDAV logic without the MCP layer.

License

MIT

Available Tools

6 tools
create_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

    A4.4/5.0

    Scored across 6 tools

    Disambiguation5/5

    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.

    Naming Consistency5/5

    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.

    Tool Count5/5

    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.

    Completeness4/5

    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

    Related MCP Servers