CalDAV MCP Server

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

Install Node.js 24+, create an Apple app-specific password, and add this local stdio server to a JSON-configured MCP client such as Claude Desktop or Gemini:

{
  "mcpServers": {
    "icloud-calendar": {
      "command": "npx",
      "args": ["--yes", "@lukegskw/caldav-mcp@latest"],
      "env": {
        "CALDAV_USERNAME": "user@example.com",
        "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.
• 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"
}

update_event

Patches an event or complete 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.

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 24+
• 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, or Node.js 24+ for npx.
• pnpm is required only when building from source. Corepack and CI use the version pinned in package.json.

npm / npx

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

CALDAV_USERNAME='user@example.com' \
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='user@example.com'
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=18100
docker 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.git
cd caldav-mcp
docker buildx build --load -t caldav-mcp:local .

Local Node.js installation

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.git
cd caldav-mcp
pnpm install --frozen-lockfile
cp .env.example .env
pnpm build
pnpm 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.

| Variable | Required | Default | Description | | ------------------------------- | -------- | --------------------------- | ------------------------------------------------- | | CALDAV_PROVIDER | No | icloud | Provider policy. iCloud is the supported profile. | | CALDAV_URL | No | https://caldav.icloud.com | CalDAV discovery URL. | | CALDAV_USERNAME | Yes | None | Apple Account email. | | CALDAV_PASSWORD | Yes | None | App-specific password, not the account password. | | CALDAV_MCP_TRANSPORT | No | stdio | stdio or streamable-http. | | CALDAV_MCP_HOST | No | 0.0.0.0 | HTTP bind address. | | CALDAV_MCP_PORT | No | 8100 | HTTP listening port. | | CALDAV_MCP_LOG_LEVEL | No | INFO