CalDAV MCP Server

CalDAV MCP Server

[TypeScript] [CI] [npm] [npm downloads] [Container] [MCP Registry] [License]

CalDAV MCP Server is a Model Context Protocol server for managing iCloud Calendar events, including native support for multiple VALARM reminders on one event.

iCloud Calendar is the only provider officially supported and manually validated in the first release. The server works with any MCP client that supports stdio or Streamable HTTP.

This independent project is not affiliated with, authorized, sponsored, or approved by Apple Inc. Apple and iCloud are trademarks of their respective owner.

Quick start

Create an Apple app-specific password, then pick the option for your client.

Claude Desktop (one click, no Node.js install): download caldav-mcp.mcpb, open it with Claude Desktop, and enter your Apple Account email and app-specific password. See Claude Desktop extension.

Any other stdio client: install Node.js 22 or newer and add this server to a JSON-configured MCP client such as Gemini CLI or Claude Code:

{  "mcpServers": {    "icloud-calendar": {      "command": "npx",      "args": ["--yes", "@lukegskw/caldav-mcp@latest"],      "env": {        "CALDAV_USERNAME": "[email protected]",        "CALDAV_PASSWORD": "xxxx-xxxx-xxxx-xxxx"      }    }  }}

Restart the client and confirm that it lists six calendar tools. See client-specific setup and Docker deployment below. Keep the configuration file private because it contains the app-specific password.

Navigation

• About
• Features
• MCP tools
• Tech stack
• Installation
• Configuration
• MCP client setup
• Verification
• Limitations
• Contributing
• Releasing

About

The server connects one configured account to iCloud through CalDAV. It discovers the account's calendars and exposes normalized read and write operations through MCP.

Updates preserve the complete iCalendar resource, including unknown properties, Apple extensions, VTIMEZONE, recurrence exceptions, and alarms omitted from a patch. Writes use opaque resource identifiers and ETags instead of assuming that a CalDAV filename matches an event UID.

Calendar resources are processed in memory. The server has no telemetry and no application database, and raw iCalendar is returned only when explicitly requested.

Features

• Discovers calendars available to the configured iCloud account.
• Lists events in semi-open time ranges and expands recurring occurrences.
• Creates timed, all-day, and recurring events.
• Supports zero, one, or multiple display alarms per event.
• Reads and writes Apple Calendar travel time (X-APPLE-TRAVEL-DURATION).
• Emits the Apple alarm extensions expected by iCloud Calendar.
• Reads events by opaque resource ID or by calendar ID and UID.
• Applies partial updates while preserving omitted and unknown iCalendar data.
• Uses ETags for optimistic concurrency on updates and deletions.
• Rejects isolated recurrence mutations instead of changing the complete series.
• Redacts credentials, raw calendar content, and CalDAV paths from logs and errors.
• Runs as a non-root container with a read-only root filesystem configuration.
• Supports stdio and Streamable HTTP MCP transports.

MCP tools

list_calendars

Lists the calendars discovered for the configured account. Each result includes an opaque calendar_id, display name, description, timezone, and best-effort write status.

list_events

Lists events in a semi-open interval and expands recurring occurrences. The maximum range is 366 days, the default page size is 100, and the maximum page size is 500. Results use a deterministic chronological order. Pagination cursors are opaque and do not represent a snapshot when events are modified during traversal.

Example input:

{  "calendar_id": "opaque-calendar-id",  "start": "2026-09-01T00:00:00Z",  "end": "2026-10-01T00:00:00Z",  "timezone": "Europe/Berlin",  "limit": 100}

get_event

Reads an event by resource_id, or by a calendar_id and UID pair. Raw iCalendar is excluded by default and can be requested with include_raw_ical: true for controlled diagnostics.

create_event

Creates an event and reads back the representation stored by the server.

Timed event with two alarms:

{  "calendar_id": "opaque-calendar-id",  "summary": "Buy Shinkansen tickets",  "start": {    "date_time": "2026-09-06T03:00:00+02:00",    "timezone": "Europe/Berlin"  },  "end": {    "date_time": "2026-09-06T03:30:00+02:00",    "timezone": "Europe/Berlin"  },  "description": "Smart-EX",  "location": null,  "alarms": [    { "minutes_before": 1440, "action": "DISPLAY" },    { "minutes_before": 0, "action": "DISPLAY" }  ],  "rrule": null}

All-day event with an exclusive end date:

{  "calendar_id": "opaque-calendar-id",  "summary": "Trip",  "start": { "date": "2026-09-06" },  "end": { "date": "2026-09-08" },  "alarms": []}

Recurring events accept an RFC 5545 rule without the RRULE: prefix:

{  "calendar_id": "opaque-calendar-id",  "summary": "Weekly planning",  "start": {    "date_time": "2026-09-07T09:00:00+02:00",    "timezone": "Europe/Berlin"  },  "end": {    "date_time": "2026-09-07T09:30:00+02:00",    "timezone": "Europe/Berlin"  },  "rrule": "FREQ=WEEKLY;BYDAY=MO;COUNT=10"}

Timed event with 30 minutes of Apple Calendar travel time:

{  "calendar_id": "opaque-calendar-id",  "summary": "Dentist",  "start": {    "date_time": "2026-10-05T10:00:00+02:00",    "timezone": "Europe/Amsterdam"  },  "end": {    "date_time": "2026-10-05T10:30:00+02:00",    "timezone": "Europe/Amsterdam"  },  "travel_minutes": 30}

travel_minutes sets a fixed travel duration before the event. In this example, travel starts at 09:30 and the appointment stays at 10:00–10:30. The server accepts whole minutes from 1 to 1,440 for timed events; omit the field or use null when creating an event without travel time. It does not calculate routes or change the event's start, end, or alarms.

The duration is stored in Apple's X-APPLE-TRAVEL-DURATION extension. Display in other calendar clients depends on their support for that extension. Returned events include travel_minutes, rounded to the nearest whole minute, or null when the duration is missing, invalid, or rounds to zero.

update_event

Patches an event or the master event of a recurring series. Omitted fields are preserved, null removes a nullable field, and alarms: [] removes all alarms. An optional expected_etag prevents overwriting a newer server version.

For travel time, omit patch.travel_minutes to keep the current value, set it to a number to replace the duration, or set it to null to remove the duration and related Apple routing metadata. For example, "patch": { "travel_minutes": null } clears travel time. When converting an event with travel time to all-day, include travel_minutes: null alongside the new start and end dates. Existing recurrence exceptions retain their own travel settings.

delete_event

Deletes an event or complete recurring series, optionally requiring an observed ETag. Deleting a single expanded occurrence is not supported in the current release.

Tech stack

• Node.js 22+ (see Node.js requirements)
• TypeScript with strict project rules
• Model Context Protocol TypeScript SDK
• tsdav
• ical.js
• Zod
• Vitest
• pnpm
• Docker

Installation

Prerequisites

• An iCloud account with Calendar enabled.
• Two-factor authentication enabled for the Apple Account.
• An app-specific password.
• Docker and Docker Compose for container deployment, Node.js 22+ for npx, or Claude Desktop for the one-click extension.
• pnpm is required only when building from source. Corepack and CI use the version pinned in package.json.

Node.js requirements

engines.node in package.json is >=22. Node.js 20 reached end of life in April 2026 and is not supported; npm prints an EBADENGINE warning on older versions. Check the version your MCP client will use with node --version. Desktop clients may use a different node than your terminal, so if a client cannot start the server, point it at the absolute path of a Node.js 22+ npx (command -v npx on macOS/Linux, where npx on Windows).

npm / npx

No global install or repository clone is required. MCP clients can launch the latest published package directly:

CALDAV_USERNAME='[email protected]' \CALDAV_PASSWORD='xxxx-xxxx-xxxx-xxxx' \npx --yes @lukegskw/caldav-mcp@latest

The command waits for MCP messages on stdin and normally prints nothing to stdout. In practice, add it to the client configuration as shown in MCP client setup. For reproducible environments, replace latest with an exact published version such as X.Y.Z.

Docker Compose

The recommended installation uses the published multi-architecture image:

ghcr.io/lukegskw/caldav-mcp:latest

Download the Compose example:

curl -O https://raw.githubusercontent.com/lukegskw/caldav-mcp/main/compose.example.yaml

Provide the Apple Account email and app-specific password, then start the service:

export CALDAV_USERNAME='[email protected]'export CALDAV_PASSWORD='xxxx-xxxx-xxxx-xxxx'docker compose -f compose.example.yaml up -d

To publish a different host port, set:

export CALDAV_MCP_PUBLISHED_PORT=18100docker compose -f compose.example.yaml up -d

The latest tag follows the newest stable release. Stable releases also publish an exact tag such as 0.1.6 and a minor-series tag such as 0.1. The Compose example pins latest by digest so deployments are reproducible. To upgrade, download the updated Compose example or replace the full image reference with the desired published version and digest.

The Streamable HTTP endpoint will be available at:

http://<host>:8100/mcp

The host port can change without changing port 8100 inside the container. No persistent volume is required; calendar data remains in iCloud.

Docker run

The same hardened container configuration can be started directly:

docker run -d \  --name caldav-mcp \  --restart unless-stopped \  --read-only \  --user 10001:10001 \  --cap-drop ALL \  --security-opt no-new-privileges:true \  --tmpfs /tmp:size=16m,mode=1777 \  -e CALDAV_PROVIDER=icloud \  -e CALDAV_USERNAME \  -e CALDAV_PASSWORD \  -e CALDAV_MCP_TRANSPORT=streamable-http \  -e CALDAV_MCP_HOST=0.0.0.0 \  -p 8100:8100 \  ghcr.io/lukegskw/caldav-mcp:latest

Build the container from source

Building locally is optional. Prefer the published image unless you need to modify or audit the container build.

git clone https://github.com/lukegskw/caldav-mcp.gitcd caldav-mcpdocker buildx build --load -t caldav-mcp:local .

Local Node.js installation

Building from source requires Node.js 22.13 or newer; Node.js 24 is recommended. Builds and typechecks use TypeScript 7. The typescript dependency aliases @typescript/typescript6 for ESLint, which still requires the TypeScript 6 API; @typescript/native supplies TypeScript 7’s tsc executable. See the TypeScript migration guidance.

git clone https://github.com/lukegskw/caldav-mcp.gitcd caldav-mcppnpm install --frozen-lockfilecp .env.example .envpnpm buildpnpm start -- --transport stdio

In stdio mode, stdout is reserved exclusively for MCP messages. To run Streamable HTTP locally:

CALDAV_MCP_TRANSPORT=streamable-http pnpm start

Configuration

All settings use the CALDAV_ or CALDAV_MCP_ prefix.

The core retains an experimental generic provider policy and configurable URL to keep Apple extensions isolated from the shared iCalendar implementation. No compatibility with other providers is currently claimed.

Secrets must be supplied through the deployment platform or environment. Never commit .env, pass credentials as MCP tool arguments, or include them in diagnostic reports.

MCP client setup

Claude Desktop extension (recommended)

Claude Desktop for macOS and Windows installs the server as a one-click MCP Bundle and runs it with its built-in Node.js:

1. Download caldav-mcp.mcpb from the latest release.
2. Open it with Claude Desktop (double-click it, or drag it onto Settings -> Extensions) and choose Install.
3. Enter the Apple Account email and app-specific password. The password is stored as a sensitive setting.

To upgrade, install the .mcpb from a newer release. See Claude Desktop extension for bundle contents and how it is built and released.

Gemini CLI extension

Install directly from GitHub and enable automatic extension updates:

gemini extensions install https://github.com/lukegskw/caldav-mcp --auto-update

Gemini prompts for the username and stores the app-specific password as a sensitive setting. The public extension gallery discovers tagged releases from this repository.

Manual configuration

For any MCP client that accepts Streamable HTTP server definitions, configure the URL:

mcp_servers:  caldav:    url: http://<host>:8100/mcp

If the client shares the Compose network, use the service name and internal port:

mcp_servers:  caldav:    url: http://caldav-mcp:8100/mcp

For clients that launch local stdio servers, prefer the npm command from Quick start. If a desktop client cannot find npx, use the absolute path reported by command -v npx on macOS/Linux or where npx on Windows.

Claude Desktop

The extension is the simplest option. To configure the server manually instead, add the Quick start JSON under mcpServers in claude_desktop_config.json, then completely restart Claude Desktop. Open the file through Settings -> Developer -> Edit Config instead of assuming its location.

Claude Code

Claude Code can add the same stdio server at user scope:

claude mcp add --transport stdio --scope user \  --env [email protected] \  --env CALDAV_PASSWORD=xxxx-xxxx-xxxx-xxxx \  icloud-calendar -- npx --yes @lukegskw/caldav-mcp@latest

This command places the values in Claude's MCP configuration. Avoid running it where shell history is shared or retained insecurely.

Codex

Codex can add the server to its shared CLI and IDE configuration:

codex mcp add icloud-calendar \  --env [email protected] \  --env CALDAV_PASSWORD=xxxx-xxxx-xxxx-xxxx \  -- npx --yes @lukegskw/caldav-mcp@latest

Run codex mcp list to verify it. For finer control, use the official Codex MCP configuration in ~/.codex/config.toml or a project-scoped .codex/config.toml.

Gemini CLI

Following the Gemini CLI MCP configuration, add the server under mcpServers in ~/.gemini/settings.json (user scope) or the project's .gemini/settings.json:

{  "mcpServers": {    "icloud-calendar": {      "command": "npx",      "args": ["--yes", "@lukegskw/caldav-mcp@latest"],      "env": {        "CALDAV_USERNAME": "[email protected]",        "CALDAV_PASSWORD": "xxxx-xxxx-xxxx-xxxx"      }    }  }}

Claude Desktop (Docker, stdio alternative)

Claude Desktop launches local stdio servers as subprocesses. Running the published container this way keeps the app-specific password on the client machine and opens no network port, which matches the transport guidance in Limitations.

Add the server to claude_desktop_config.json:

{  "mcpServers": {    "icloud-calendar": {      "command": "/absolute/path/to/docker",      "args": [        "run",        "-i",        "--rm",        "--env-file",        "/absolute/path/to/caldav-mcp.env",        "-e",        "CALDAV_PROVIDER=icloud",        "-e",        "CALDAV_MCP_TRANSPORT=stdio",        "ghcr.io/lukegskw/caldav-mcp@sha256:<digest>"      ]    }  }}

-i is required. Without an attached stdin the client cannot speak MCP to the container. --rm removes the container once the client stops it.

Supply credentials through --env-file rather than -e. Arguments passed to docker run are visible in the host process list; the contents of an env file are not. The file holds the variables described in Configuration:

[email protected]CALDAV_PASSWORD=xxxx-xxxx-xxxx-xxxx

Pin the image by digest instead of latest, so that restarting the client cannot silently start a different version:

docker pull ghcr.io/lukegskw/caldav-mcp:latestdocker images --digests ghcr.io/lukegskw/caldav-mcp

Restart Claude Desktop completely after editing the configuration file.

Windows

When Claude Desktop is installed from the Microsoft Store, Windows redirects %APPDATA%\Claude into the package container and the file lives at:

%LOCALAPPDATA%\Packages\Claude_<package-id>\LocalCache\Roaming\Claude\claude_desktop_config.json

In that case dir %APPDATA%\Claude reports nothing. Server logs are written next to the configuration file, in logs\mcp-server-<server-name>.log.

Use the absolute path to docker.exe, because PATH inside the package container is not reliable. where docker prints it, typically C:\Program Files\Docker\Docker\resources\bin\docker.exe. Backslashes must be escaped in JSON.

Configuration formats differ between MCP clients. Consult the client's documentation for its exact schema and reload or restart it after changing the server definition.

Verification

Check the container state and logs:

docker compose -f compose.example.yaml psdocker compose -f compose.example.yaml logs caldav-mcp

The container should report healthy. The TCP healthcheck validates the server process, not iCloud credentials.

Run the repository verification suite:

pnpm install --frozen-lockfilepnpm format:checkpnpm lintpnpm typecheckpnpm test:unitpnpm test:integrationpnpm buildpnpm test:packagepnpm test:distributionpnpm build:mcpbpnpm test:mcpb

Finally, connect with an MCP client and confirm that all six tools are listed.

Limitations

• One iCloud account is configured per server process or container.
• The Streamable HTTP endpoint has no authentication in the current release. Restrict it to a trusted LAN, VPN, or private container network; do not expose it directly to the internet.
• Individual recurrence occurrences are read-only. Updating or deleting the complete series is supported.
• Only ACTION:DISPLAY alarms are created.
• Individual iCalendar resources are limited to 5 MiB.
• Event list ranges are limited to 366 days and pages to 500 results.
• Events may contain at most 20 alarms.
• Attendee scheduling is outside the current scope.
• Providers other than iCloud are not officially supported.

Review SECURITY.md before reporting a security issue or attaching diagnostics.

Contributing

Contributions are welcome. Before opening a pull request:

pnpm install --frozen-lockfilepnpm format:checkpnpm lintpnpm typecheckpnpm testpnpm builddocker buildx build --load -t caldav-mcp:test .

Changes to CalDAV writes or iCalendar serialization must preserve ETag checks, opaque resource boundaries, unknown properties, recurrence exceptions, and alarms omitted from patches. TypeScript changes must continue to satisfy the rules in .codex/rules/typescript.md.

Releasing

Releases are version-driven and automated from main so that a partial registry outage can be retried without publishing a second npm version.

1. Prepare the new version with pnpm release:prepare X.Y.Z. This synchronizes the npm, MCP Registry, Gemini, and MCP Bundle (manifest.json) metadata.
2. Run the verification suite, including pnpm test:distribution and pnpm test:mcpb.
3. Commit and push the release changes to main.
4. The release workflow validates the commit and creates the matching vX.Y.Z tag automatically before publishing.

The release workflow validates the versions, tests the packed npm artifact and the Claude Desktop bundle, and publishes the exact, minor-series, and latest container tags together with the npm package, MCP Registry entry, and GitHub release with caldav-mcp.mcpb attached. Prereleases receive only their exact container tag. Gemini can discover the tagged extension without another per-release edit. A rerun skips matching artifacts that already exist and resumes the missing steps. See Claude Desktop extension for building, testing, and shipping the .mcpb bundle.

License

MIT. See LICENSE.