How do I install ICloud Calendar (CalDAV)?

Copy the stdio config for Cursor, Claude Desktop, Claude Code, or VS Code on this page. It uses the publisher's install, not a PlugMCP proxy.

Does ICloud Calendar (CalDAV) need an API key?

The publisher lists these environment variables: ICLOUD_USERNAME, ICLOUD_PASSWORD, MCP_ICAL_READ_ONLY, MCP_ICAL_LOG_LEVEL.

What transport does ICloud Calendar (CalDAV) use?

ICloud Calendar (CalDAV) runs locally over stdio.

When was ICloud Calendar (CalDAV) last checked?

Last checked 2026-11-09. iCloud Calendar over CalDAV: list, create, update, move and delete events. Optional read-only mode.

ICloud Calendar (CalDAV) MCP server

Power your agent

Add this server

The publisher's own command. Not a PlugMCP endpoint.

Add to Cursor Add to VS Code Run on PlugMCP

Host a copy with our keys and logs.

Local command

uvx mcp-icloud-caldav==0.2.1

Credentials from the publisher

ICLOUD_USERNAME — Apple ID email address
ICLOUD_PASSWORD — App-specific password from appleid.apple.com (not the Apple ID password)
MCP_ICAL_READ_ONLY — Set to true to leave out the create, update and delete tools
MCP_ICAL_LOG_LEVEL — Log level on stderr: TRACE, DEBUG, INFO, WARNING or ERROR

Claude Code has no install link for a local command. Copy the command below and run it in a terminal.

shClaude Code

1ICLOUD_USERNAME=<value> ICLOUD_PASSWORD=<secret> MCP_ICAL_READ_ONLY=<value> MCP_ICAL_LOG_LEVEL=<value> claude mcp add io.github.glob0x17-mcp-icloud-caldav -- uvx mcp-icloud-caldav==0.2.1

Run in a terminal.

jsonClaude Desktop

1{2  "mcpServers": {3    "io.github.glob0x17-mcp-icloud-caldav": {4      "command": "uvx",5      "args": [6        "mcp-icloud-caldav==0.2.1"7      ],8      "env": {9        "ICLOUD_USERNAME": "<value>",10        "ICLOUD_PASSWORD": "<secret>",11        "MCP_ICAL_READ_ONLY": "<value>",12        "MCP_ICAL_LOG_LEVEL": "<value>"13      }14    }15  }16}

claude_desktop_config.json

Local · pypiPublisher installStep-by-step: add this in Claude

Remote URL or a command on your machine? How the two installs differ

Run on PlugMCP

Host a copy with our keys and logs.

A new server you create. It is not this listing's official endpoint. Use the publisher install when you want their URL and their credentials.

Launch

Server facts

Local

Transport: stdio
Version: 0.2.1

Tools

No tool list yet. Remote servers get one after the first health check.

FAQ

Questions

iCloud Calendar MCP Server

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.

This is a maintained fork of zwrong/iCalendar, itself derived from the macOS mcp-ical server. See Changes in this fork.

Tools

Tool	Description
`list_calendars`	Names of the available calendars
`list_events`	Events in a date range, optionally for one calendar, sorted by start time
`create_event`	New event: title, times, all-day, location, notes, URL, alarms, recurrence
`update_event`	Change any of those fields, or move the event to another calendar
`delete_event`	Delete an event by identifier
`debug_calendar_connection`	Connection check: calendars and event counts over the last 7 days

The calendars://list resource also lists the calendars. With MCP_ICAL_READ_ONLY=true, the three write tools are not registered at all.

Requirements

Python 3.12 or later and uv
An Apple ID with iCloud Calendar enabled
An app-specific password for that Apple ID

App-specific password

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

Configuration

Credentials are read in this order:

Environment variables (recommended)

Variable Required Default
ICLOUD_USERNAME yes
ICLOUD_PASSWORD yes
CALDAV_SERVER_URL no https://caldav.icloud.com/
MCP_ICAL_CONFIG: path to a JSON file shaped like config.json.example
config_private.json, then config.json, at the repository root (kept for compatibility)

Variable	Required	Default
`ICLOUD_USERNAME`	yes
`ICLOUD_PASSWORD`	yes
`CALDAV_SERVER_URL`	no	`https://caldav.icloud.com/`

Other settings:

Variable	Default	Effect
`MCP_ICAL_READ_ONLY`	`false`	`true` leaves out `create_event`, `update_event` and `delete_event`
`MCP_ICAL_LOG_LEVEL`	`INFO`	`TRACE`, `DEBUG`, `INFO`, `WARNING` or `ERROR`. Logs go to stderr

The server speaks MCP over stdio and is started by the client. To check it by hand:

[email protected] ICLOUD_PASSWORD=xxxx-xxxx-xxxx-xxxx uvx mcp-icloud-caldav

It waits on stdin and prints nothing on stdout.

Client setup

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:

mkdir -p ~/.config/mcp-icloud-caldav && chmod 700 ~/.config/mcp-icloud-caldav
cat > ~/.config/mcp-icloud-caldav/env <<'EOF'
[email protected]
ICLOUD_PASSWORD=xxxx-xxxx-xxxx-xxxx
MCP_ICAL_READ_ONLY=true
EOF
chmod 600 ~/.config/mcp-icloud-caldav/env

cat > ~/.local/bin/mcp-icloud-caldav-run <<'EOF'
#!/usr/bin/env bash
set -euo pipefail
set -a; source "$HOME/.config/mcp-icloud-caldav/env"; set +a
exec /absolute/path/to/uvx mcp-icloud-caldav
EOF
chmod +x ~/.local/bin/mcp-icloud-caldav-run

Then point the client at ~/.local/bin/mcp-icloud-caldav-run. Starting read-only and switching to false once reading works is a sensible first step.

Claude Desktop

In claude_desktop_config.json (Settings, Developer, Edit Config). On macOS it is ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "icloud-calendar": {
      "command": "uvx",
      "args": ["mcp-icloud-caldav"],
      "env": {
        "ICLOUD_USERNAME": "[email protected]",
        "ICLOUD_PASSWORD": "xxxx-xxxx-xxxx-xxxx"
      }
    }
  }
}

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.

Credits and license

MIT, see LICENSE.

The original macOS mcp-ical server (Omar D.), whose copyright notice is kept in LICENSE
zwrong/iCalendar, the iCloud CalDAV port this fork builds on
python-caldav and the Model Context Protocol Python SDK

Add this server

Host a copy with our keys and logs.

Server facts

Tools

Questions

How do I install ICloud Calendar (CalDAV)?

Does ICloud Calendar (CalDAV) need an API key?

What transport does ICloud Calendar (CalDAV) use?

When was ICloud Calendar (CalDAV) last checked?

Documentation

iCloud Calendar MCP Server

Tools

Requirements

App-specific password

Installation

Configuration

Client setup

Keeping the password out of the client config

Claude Desktop

Claude Code

Other clients

Behavior worth knowing

Privacy and security

Troubleshooting

Development

Changes in this fork

Credits and license