Skip to main content
Glama
iCloud Calendar MCP
by samkorn

iCloud Calendar MCP on Modal

A remote MCP server that gives Claude read/write access to your iCloud calendars over CalDAV. It runs on Modal and is added to Claude as a custom connector, so it works in Claude on web, desktop, mobile and in cloud tasks.

It authenticates to iCloud with an Apple app-specific password, and Claude authenticates to the server with a bearer token.

This is a personal project. It is not affiliated with or endorsed by Apple, Anthropic or Modal.

Tools

Tool

What it does

list_calendars

Names of your calendars

list_events

Events in a time range, optionally filtered by text

list_busy_times

When you are busy in a time range, with no event details

get_event

One event in full, with its invitees and repeat rule

create_event

New timed, all-day or recurring event

update_event

Change an event, or one occurrence of a recurring one

delete_event

Delete an event, one occurrence, or the rest of a series

An event can have a title, time, location, description, web link and alerts, and can be marked as free time. With a place's coordinates as well as its name, Apple's Calendar shows a map for it; that part has been checked only against what Apple's own apps store, not by looking at the result in Calendar.

Recurring events are listed one occurrence at a time. To change or delete one, Claude has to say what it means: one occurrence, that occurrence and every later one (delete only), or the whole series. Without that the call is refused, so "delete Tuesday's standup" can't quietly delete all of them.

Every event comes with the version that was read (its etag), and update_event and delete_event have to name it. If the event has changed since Claude read it, on your phone or by someone who shares the calendar, nothing happens and Claude is told to look again.

The tools can't invite anyone or reply to an invitation: both make iCloud send mail to other people, and nothing on the server could hold that back.

Events that already have invitees are a special case. iCloud may notify them when such an event is changed or deleted, so list_events marks it has_invitees, and update_event and delete_event refuse it until they are called again with invitees_confirmed. Claude is told to ask you first, and to say that invitees may be notified. Whether iCloud really sends anything has not been tested, hence "may".

One list_events call covers at most 366 days and 1000 events; past that it fails and says so, rather than returning part of the list. New recurring events repeat daily or less often. A stored series that costs too much to expand (one that repeats every few seconds, say) is listed once and marked occurrences_omitted.

Related MCP server: garmin-claude-mcp

What you need

  • An Apple account with iCloud calendars and two-factor authentication turned on. Apple only issues app-specific passwords to accounts that have it.

  • A Modal account. The free Starter plan includes $30 of credits a month, and this server is sized to use a small fraction of that.

  • A Claude account that can send request headers to a custom connector. That option is in beta and not on every account, so check before you start: in Claude, open Customize > Connectors > Add custom connector and look for a "Request headers" section. Without it, Claude has no way to send this server its token.

  • A terminal on macOS or Linux. The commands below are written for one.

You don't need Python installed. uv, installed in step 2, fetches it.

Setup

Nine short steps. Step 7 is optional.

1. Get the code

Download the repository:

git clone https://github.com/samkorn/icloud-calendar-mcp.git

Move into it. Every later command is run from this folder:

cd icloud-calendar-mcp

2. Install uv and the dependencies

uv is the Python package manager this project uses. If you don't have it, install it (the uv docs list other ways, such as brew install uv):

curl -LsSf https://astral.sh/uv/install.sh | sh

Then install the project:

uv sync

This downloads Python 3.14 if you don't have it, creates a .venv folder here, and installs the exact package versions recorded in uv.lock, including Modal's command-line tool. Nothing is installed system-wide: the packages go in this folder, and uv keeps the Python it downloads and its cache in your home directory. Every command from here on starts with uv run, which runs it inside that environment.

3. Connect to Modal

If you don't have a Modal account, create one at modal.com. Then log this computer in:

uv run modal setup

This opens your browser and asks you to sign in to Modal and approve a new API token, which it saves to ~/.modal.toml. When the terminal prints "Token verified successfully!", you're done. That is all the Modal setup there is: the remaining steps create everything else from the command line.

4. Create an app-specific password for iCloud

This is the password the server uses to reach your calendars, in place of your real Apple password.

  1. Sign in at account.apple.com.

  2. Open Sign-In and Security > App-Specific Passwords.

  3. Add one and name it icloud-calendar-mcp.

  4. Copy the password Apple shows (xxxx-xxxx-xxxx-xxxx). You'll paste it into .env in step 6.

Make a new one just for this server and don't reuse it. An app-specific password also works for iCloud mail and contacts, so you want to be able to revoke this one on its own.

5. Create the token Claude will send

The server only answers requests that carry a secret token. That token is a Modal proxy auth token. Create one:

uv run modal workspace proxy-tokens create --name icloud-calendar-mcp

Modal prints a small table. Find the line that reads Authorization: Bearer wk-....ws-... and copy everything after Bearer : the token ID and the token secret, joined by a period. You'll paste it into .env in the next step. The secret is shown only this once; if you lose it, delete the token and create another (see "Change the token").

A proxy token is not tied to one app. Unless your workspace uses Modal's RBAC, where tokens are limited to the environments you pick, it is accepted by every proxy-protected endpoint in the workspace. If you run other endpoints that rely on proxy auth alone, this token opens those too, so think about where you paste it.

6. Fill in .env

.env is the file that holds your three secrets on this computer. Git ignores it, so it can't be committed by accident. Create it from the template:

cp .env.example .env

Open .env in a text editor and put each value after its =, with no quotes or spaces:

Key

Value

ICLOUD_USERNAME

Your Apple ID email

ICLOUD_APP_PASSWORD

The app-specific password from step 4

MCP_AUTH_TOKEN

The wk-....ws-... token from step 5

7. Try it locally (optional)

This checks your iCloud login before anything is deployed. Start the server on your own machine:

uv run --env-file .env python server.py

--env-file .env makes uv load your three secrets into the server's environment. The server listens on http://127.0.0.1:8000/mcp, reachable only from this computer, and keeps running until you press Ctrl+C.

In a second terminal, in the same folder, ask it for your calendars:

uv run --env-file .env sh -c 'curl -s http://127.0.0.1:8000/mcp \
  -H "Authorization: Bearer $MCP_AUTH_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d "{\"jsonrpc\": \"2.0\", \"id\": 1, \"method\": \"tools/call\", \"params\": {\"name\": \"list_calendars\", \"arguments\": {}}}"'

This sends one list_calendars call with your token, which uv reads from .env so you never type it. The reply is a line of JSON containing your calendar names. If it holds an error message instead, check the Apple ID email and app-specific password in .env, restart the server and try again.

To explore the other tools by hand, the MCP Inspector can connect to the same URL over Streamable HTTP with an Authorization header of Bearer <your MCP_AUTH_TOKEN>.

8. Deploy to Modal

Copy the three values from .env into a Modal Secret named icloud-calendar-mcp, which is where the deployed server reads them from:

uv run modal secret create icloud-calendar-mcp --from-dotenv .env

Build and deploy the server:

uv run modal deploy modal_app.py

The first deploy is the slow one, because Modal builds the image. When it finishes, Modal prints the URL of the web function, ending in .modal.run. The MCP server is at that URL plus /mcp. Keep it for the next step.

To confirm the endpoint is locked, request it without the token (put your own URL in):

curl -i https://YOUR-URL.modal.run/mcp

The first line of the reply should be a 401. That is Modal refusing a request that has no token.

If the deploy fails with "Unsupported Python version: '3.14'", your Modal workspace is on an old image builder version. Raise it in the Modal dashboard under Settings > Image Config, or override it for this deploy:

MODAL_IMAGE_BUILDER_VERSION=2026.10 uv run modal deploy modal_app.py

The deployment scales to zero when idle and is capped at one small CPU-only container, so it costs little or nothing on Modal's free credits. The first request after an idle period takes a few seconds while a container starts.

9. Add it to Claude

In Claude, open Customize > Connectors > Add custom connector:

  • URL: your Modal URL plus /mcp

  • Transport: Streamable HTTP

  • Authentication: No sign-in

  • Request headers: name authorization, value Bearer <your MCP_AUTH_TOKEN> (type the Bearer prefix yourself, then paste the token from .env)

Then ask Claude something like "What's on my calendar this week?" to see it work.

Once it is added, the connector's page in the same settings lists the tools, and each can be set to always allowed, needing approval, or blocked. To let Claude see your calendars without being able to change them, block create_event, update_event and delete_event. "Needs approval" is the default for those three, but the note on that page says Claude does not ask in every mode, so block a tool you never want used rather than count on being asked.

After setup

Update the server

Fetch the latest code:

git pull

Deploy it. This replaces the running version and keeps the same URL, so nothing changes in Claude:

uv run modal deploy modal_app.py

See the logs

Print the deployed server's recent log lines, which record each tool call's name and how long it took, never calendar contents:

uv run modal app logs icloud-calendar-mcp

Change the token

Claude does not let you edit a connector's authentication afterwards, so replacing the token means going back through a few of the setup steps:

  1. Create a new proxy token (step 5) and put it in .env as MCP_AUTH_TOKEN.

  2. Overwrite the Modal Secret with the new values:

    uv run modal secret create icloud-calendar-mcp --from-dotenv .env --force
  3. Redeploy so the server picks up the new secret:

    uv run modal deploy modal_app.py
  4. In Claude, remove the connector and add it again with the new token (step 9).

  5. Find the old token's ID (it starts with wk-):

    uv run modal workspace proxy-tokens list
  6. Delete the old token, so it stops working:

    uv run modal workspace proxy-tokens delete <token-id>

Take it down

Stop the server for good. Its URL stops answering:

uv run modal app stop icloud-calendar-mcp

Delete the stored secrets from Modal:

uv run modal secret delete icloud-calendar-mcp

Then delete the proxy token as in "Change the token", remove the connector in Claude, and revoke the app-specific password at account.apple.com.

Development

Run the tests. They reach nothing beyond a server they start on your own machine, and need no iCloud account or .env:

uv run pytest

Security

The Modal URL is public, and two layers keep everyone else out. Both check the same Authorization header:

  1. Modal's proxy auth rejects a request without a valid proxy token before it reaches the server, so strangers can't start a container.

  2. The server itself then compares the header to MCP_AUTH_TOKEN and rejects anything else before doing any work. This keeps the endpoint closed even if the Modal setting is ever turned off.

Anyone who has the token can read and change your calendars: keep it out of chats, logs and screenshots, and replace it if it leaks. Secrets live only in .env (ignored by git) and the Modal Secret.

Past the token check, the server:

  • accepts only requests addressed to its own host (*.modal.run when deployed; edit ALLOWED_HOSTS in modal_app.py if you use your own domain) and refuses requests that come from a web page;

  • sends your iCloud password only to iCloud's own calendar servers, over HTTPS, and refuses a redirect that points anywhere else;

  • gives up on iCloud after 20 seconds of silence on a request and 45 seconds per tool call, and sends no change once that time is up;

  • accepts at most 8 MiB from iCloud in answer to one request;

  • stops working out a recurring event's occurrences after 2 seconds of processor time, and lists it once instead;

  • reports errors and warnings from calendar operations without calendar names, event text or iCloud's replies, in both the response and the logs (an argument of the wrong type is refused earlier, and that reply quotes the argument back to whoever sent it);

  • fails a listing if iCloud left out an event's data and it couldn't be fetched, rather than return the list without that event;

  • changes or deletes an event only if it hasn't changed since Claude read it;

  • changes a recurring event only as far as the call says: one occurrence, the rest of the series, or all of it.

Calendar names, and the titles and descriptions on shared calendars and invitations, are written by other people. Claude is told to treat them as data and not to act on requests in them, but that is advice, not a lock: the token reaches every calendar, and the server does not limit what Claude does with it. Keep approval on for the tools that change things, or block them (see step 9).

To report a security problem, see SECURITY.md.

License

MIT.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      Not graded
      maintenance
      Enables Claude to read recent training activities and wellness signals such as sleep, HRV, and resting heart rate, then design structured workouts that are written to an intervals.icu calendar and synced onward to Garmin Connect and the user's watch. Also supports listing, editing, and deleting planned workouts.
      MIT
    • A
      license
      Not graded
      quality
      Not graded
      maintenance
      Enables Claude to read recent activities and wellness metrics (sleep, HRV, resting heart rate) and to create, update, or delete structured workouts pushed to an intervals.icu calendar that syncs to Garmin Connect and the user's watch.
      MIT