{
  "markdown": "# CalDAV MCP Server\n\n[![TypeScript](https://img.shields.io/badge/TypeScript-strict-3178C6?logo=typescript&logoColor=white)](https://www.typescriptlang.org/)\n[![CI](https://github.com/lukegskw/caldav-mcp/actions/workflows/container.yml/badge.svg)](https://github.com/lukegskw/caldav-mcp/actions/workflows/container.yml)\n[![npm](https://img.shields.io/npm/v/@lukegskw/caldav-mcp?logo=npm)](https://www.npmjs.com/package/@lukegskw/caldav-mcp)\n[![npm downloads](https://img.shields.io/npm/dm/@lukegskw/caldav-mcp?logo=npm)](https://www.npmjs.com/package/@lukegskw/caldav-mcp)\n[![Container](https://img.shields.io/badge/GHCR-amd64%20%7C%20arm64-2496ED?logo=docker&logoColor=white)](https://github.com/lukegskw/caldav-mcp/pkgs/container/caldav-mcp)\n[![MCP Registry](https://img.shields.io/badge/MCP_Registry-listed-5A67D8)](https://registry.modelcontextprotocol.io/?q=io.github.lukegskw%2Fcaldav-mcp)\n[![License](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)\n\n**CalDAV MCP Server** is a Model Context Protocol server for managing iCloud Calendar\nevents, including native support for multiple `VALARM` reminders on one event.\n\niCloud Calendar is the only provider officially supported and manually validated in the\nfirst release. The server works with any MCP client that supports `stdio` or Streamable\nHTTP.\n\nThis independent project is not affiliated with, authorized, sponsored, or approved by\nApple Inc. Apple and iCloud are trademarks of their respective owner.\n\n## Quick start\n\nInstall [Node.js 24+](https://nodejs.org/), create an\n[Apple app-specific password](https://support.apple.com/en-us/102654), and add this\nlocal `stdio` server to a JSON-configured MCP client such as Claude Desktop or Gemini:\n\n```json\n{\n  \"mcpServers\": {\n    \"icloud-calendar\": {\n      \"command\": \"npx\",\n      \"args\": [\"--yes\", \"@lukegskw/caldav-mcp@latest\"],\n      \"env\": {\n        \"CALDAV_USERNAME\": \"user@example.com\",\n        \"CALDAV_PASSWORD\": \"xxxx-xxxx-xxxx-xxxx\"\n      }\n    }\n  }\n}\n```\n\nRestart the client and confirm that it lists six calendar tools. See\n[client-specific setup](#mcp-client-setup) and [Docker deployment](#docker-compose)\nbelow. Keep the configuration file private because it contains the app-specific\npassword.\n\n## Navigation\n\n- [About](#about)\n- [Features](#features)\n- [MCP tools](#mcp-tools)\n- [Tech stack](#tech-stack)\n- [Installation](#installation)\n- [Configuration](#configuration)\n- [MCP client setup](#mcp-client-setup)\n- [Verification](#verification)\n- [Limitations](#limitations)\n- [Contributing](#contributing)\n- [Releasing](#releasing)\n\n## About\n\nThe server connects one configured account to iCloud through CalDAV. It discovers the\naccount's calendars and exposes normalized read and write operations through MCP.\n\nUpdates preserve the complete iCalendar resource, including unknown properties, Apple\nextensions, `VTIMEZONE`, recurrence exceptions, and alarms omitted from a patch. Writes\nuse opaque resource identifiers and ETags instead of assuming that a CalDAV filename\nmatches an event UID.\n\nCalendar resources are processed in memory. The server has no telemetry and no\napplication database, and raw iCalendar is returned only when explicitly requested.\n\n## Features\n\n- Discovers calendars available to the configured iCloud account.\n- Lists events in semi-open time ranges and expands recurring occurrences.\n- Creates timed, all-day, and recurring events.\n- Supports zero, one, or multiple display alarms per event.\n- Emits the Apple alarm extensions expected by iCloud Calendar.\n- Reads events by opaque resource ID or by calendar ID and UID.\n- Applies partial updates while preserving omitted and unknown iCalendar data.\n- Uses ETags for optimistic concurrency on updates and deletions.\n- Rejects isolated recurrence mutations instead of changing the complete series.\n- Redacts credentials, raw calendar content, and CalDAV paths from logs and errors.\n- Runs as a non-root container with a read-only root filesystem configuration.\n- Supports `stdio` and Streamable HTTP MCP transports.\n\n## MCP tools\n\n### `list_calendars`\n\nLists the calendars discovered for the configured account. Each result includes an\nopaque `calendar_id`, display name, description, timezone, and best-effort write status.\n\n### `list_events`\n\nLists events in a semi-open interval and expands recurring occurrences. The maximum\nrange is 366 days, the default page size is 100, and the maximum page size is 500.\nResults use a deterministic chronological order. Pagination cursors are opaque and\ndo not represent a snapshot when events are modified during traversal.\n\nExample input:\n\n```json\n{\n  \"calendar_id\": \"opaque-calendar-id\",\n  \"start\": \"2026-09-01T00:00:00Z\",\n  \"end\": \"2026-10-01T00:00:00Z\",\n  \"timezone\": \"Europe/Berlin\",\n  \"limit\": 100\n}\n```\n\n### `get_event`\n\nReads an event by `resource_id`, or by a `calendar_id` and UID pair. Raw iCalendar is\nexcluded by default and can be requested with `include_raw_ical: true` for controlled\ndiagnostics.\n\n### `create_event`\n\nCreates an event and reads back the representation stored by the server.\n\nTimed event with two alarms:\n\n```json\n{\n  \"calendar_id\": \"opaque-calendar-id\",\n  \"summary\": \"Buy Shinkansen tickets\",\n  \"start\": {\n    \"date_time\": \"2026-09-06T03:00:00+02:00\",\n    \"timezone\": \"Europe/Berlin\"\n  },\n  \"end\": {\n    \"date_time\": \"2026-09-06T03:30:00+02:00\",\n    \"timezone\": \"Europe/Berlin\"\n  },\n  \"description\": \"Smart-EX\",\n  \"location\": null,\n  \"alarms\": [\n    { \"minutes_before\": 1440, \"action\": \"DISPLAY\" },\n    { \"minutes_before\": 0, \"action\": \"DISPLAY\" }\n  ],\n  \"rrule\": null\n}\n```\n\nAll-day event with an exclusive end date:\n\n```json\n{\n  \"calendar_id\": \"opaque-calendar-id\",\n  \"summary\": \"Trip\",\n  \"start\": { \"date\": \"2026-09-06\" },\n  \"end\": { \"date\": \"2026-09-08\" },\n  \"alarms\": []\n}\n```\n\nRecurring events accept an RFC 5545 rule without the `RRULE:` prefix:\n\n```json\n{\n  \"calendar_id\": \"opaque-calendar-id\",\n  \"summary\": \"Weekly planning\",\n  \"start\": {\n    \"date_time\": \"2026-09-07T09:00:00+02:00\",\n    \"timezone\": \"Europe/Berlin\"\n  },\n  \"end\": {\n    \"date_time\": \"2026-09-07T09:30:00+02:00\",\n    \"timezone\": \"Europe/Berlin\"\n  },\n  \"rrule\": \"FREQ=WEEKLY;BYDAY=MO;COUNT=10\"\n}\n```\n\n### `update_event`\n\nPatches an event or complete recurring series. Omitted fields are preserved, `null`\nremoves a nullable field, and `alarms: []` removes all alarms. An optional\n`expected_etag` prevents overwriting a newer server version.\n\n### `delete_event`\n\nDeletes an event or complete recurring series, optionally requiring an observed ETag.\nDeleting a single expanded occurrence is not supported in the current release.\n\n## Tech stack\n\n- [Node.js 24+](https://nodejs.org/)\n- [TypeScript](https://www.typescriptlang.org/) with strict project rules\n- [Model Context Protocol TypeScript SDK](https://github.com/modelcontextprotocol/typescript-sdk)\n- [tsdav](https://github.com/natelindev/tsdav)\n- [ical.js](https://github.com/kewisch/ical.js)\n- [Zod](https://zod.dev/)\n- [Vitest](https://vitest.dev/)\n- [pnpm](https://pnpm.io/)\n- [Docker](https://www.docker.com/)\n\n## Installation\n\n### Prerequisites\n\n- An iCloud account with Calendar enabled.\n- Two-factor authentication enabled for the Apple Account.\n- An [app-specific password](https://support.apple.com/en-us/102654).\n- Docker and Docker Compose for container deployment, or Node.js 24+ for `npx`.\n- pnpm is required only when building from source. Corepack and CI use the version\n  pinned in `package.json`.\n\n### npm / npx\n\nNo global install or repository clone is required. MCP clients can launch the latest\npublished package directly:\n\n```sh\nCALDAV_USERNAME='user@example.com' \\\nCALDAV_PASSWORD='xxxx-xxxx-xxxx-xxxx' \\\nnpx --yes @lukegskw/caldav-mcp@latest\n```\n\nThe command waits for MCP messages on stdin and normally prints nothing to stdout. In\npractice, add it to the client configuration as shown in [MCP client setup](#mcp-client-setup).\nFor reproducible environments, replace `latest` with an exact published version such as\n`X.Y.Z`.\n\n### Docker Compose\n\nThe recommended installation uses the published multi-architecture image:\n\n```text\nghcr.io/lukegskw/caldav-mcp:latest\n```\n\nDownload the Compose example:\n\n```sh\ncurl -O https://raw.githubusercontent.com/lukegskw/caldav-mcp/main/compose.example.yaml\n```\n\nProvide the Apple Account email and app-specific password, then start the service:\n\n```sh\nexport CALDAV_USERNAME='user@example.com'\nexport CALDAV_PASSWORD='xxxx-xxxx-xxxx-xxxx'\ndocker compose -f compose.example.yaml up -d\n```\n\nTo publish a different host port, set:\n\n```sh\nexport CALDAV_MCP_PUBLISHED_PORT=18100\ndocker compose -f compose.example.yaml up -d\n```\n\nThe `latest` tag follows the newest stable release. Stable releases also publish an\nexact tag such as `0.1.6` and a minor-series tag such as `0.1`. The Compose example\npins `latest` by digest so deployments are reproducible. To upgrade, download the\nupdated Compose example or replace the full image reference with the desired\npublished version and digest.\n\nThe Streamable HTTP endpoint will be available at:\n\n```text\nhttp://<host>:8100/mcp\n```\n\nThe host port can change without changing port `8100` inside the container. No\npersistent volume is required; calendar data remains in iCloud.\n\n### Docker run\n\nThe same hardened container configuration can be started directly:\n\n```sh\ndocker run -d \\\n  --name caldav-mcp \\\n  --restart unless-stopped \\\n  --read-only \\\n  --user 10001:10001 \\\n  --cap-drop ALL \\\n  --security-opt no-new-privileges:true \\\n  --tmpfs /tmp:size=16m,mode=1777 \\\n  -e CALDAV_PROVIDER=icloud \\\n  -e CALDAV_USERNAME \\\n  -e CALDAV_PASSWORD \\\n  -e CALDAV_MCP_TRANSPORT=streamable-http \\\n  -e CALDAV_MCP_HOST=0.0.0.0 \\\n  -p 8100:8100 \\\n  ghcr.io/lukegskw/caldav-mcp:latest\n```\n\n### Build the container from source\n\nBuilding locally is optional. Prefer the published image unless you need to modify or\naudit the container build.\n\n```sh\ngit clone https://github.com/lukegskw/caldav-mcp.git\ncd caldav-mcp\ndocker buildx build --load -t caldav-mcp:local .\n```\n\n### Local Node.js installation\n\nBuilds and typechecks use TypeScript 7. The `typescript` dependency aliases\n`@typescript/typescript6` for ESLint, which still requires the TypeScript 6 API;\n`@typescript/native` supplies TypeScript 7’s `tsc` executable. See the\n[TypeScript migration guidance](https://devblogs.microsoft.com/typescript/announcing-typescript-7-0/#running-side-by-side-with-typescript-6.0).\n\n```sh\ngit clone https://github.com/lukegskw/caldav-mcp.git\ncd caldav-mcp\npnpm install --frozen-lockfile\ncp .env.example .env\npnpm build\npnpm start -- --transport stdio\n```\n\nIn `stdio` mode, stdout is reserved exclusively for MCP messages. To run Streamable HTTP\nlocally:\n\n```sh\nCALDAV_MCP_TRANSPORT=streamable-http pnpm start\n```\n\n## Configuration\n\nAll settings use the `CALDAV_` or `CALDAV_MCP_` prefix.\n\n| Variable                        | Required | Default                     | Description                                       |\n| ------------------------------- | -------- | --------------------------- | ------------------------------------------------- |\n| `CALDAV_PROVIDER`               | No       | `icloud`                    | Provider policy. iCloud is the supported profile. |\n| `CALDAV_URL`                    | No       | `https://caldav.icloud.com` | CalDAV discovery URL.                             |\n| `CALDAV_USERNAME`               | Yes      | None                        | Apple Account email.                              |\n| `CALDAV_PASSWORD`               | Yes      | None                        | App-specific password, not the account password.  |\n| `CALDAV_MCP_TRANSPORT`          | No       | `stdio`                     | `stdio` or `streamable-http`.                     |\n| `CALDAV_MCP_HOST`               | No       | `0.0.0.0`                   | HTTP bind address.                                |\n| `CALDAV_MCP_PORT`               | No       | `8100`                      | HTTP listening port.                              |\n| `CALDAV_MCP_LOG_LEVEL`          | No       | `INFO`                      | Application log level.                            |\n| `CALDAV_MCP_REQUEST_TIMEOUT_MS` | No       | `30000`                     | CalDAV request timeout.                           |\n\nThe core retains an experimental `generic` provider policy and configurable URL to keep\nApple extensions isolated from the shared iCalendar implementation. No compatibility\nwith other providers is currently claimed.\n\nSecrets must be supplied through the deployment platform or environment. Never commit\n`.env`, pass credentials as MCP tool arguments, or include them in diagnostic reports.\n\n## MCP client setup\n\n### Gemini CLI extension\n\nInstall directly from GitHub and enable automatic extension updates:\n\n```sh\ngemini extensions install https://github.com/lukegskw/caldav-mcp --auto-update\n```\n\nGemini prompts for the username and stores the app-specific password as a sensitive\nsetting. The public extension gallery discovers tagged releases from this repository.\n\n### Manual configuration\n\nFor any MCP client that accepts Streamable HTTP server definitions, configure the URL:\n\n```yaml\nmcp_servers:\n  caldav:\n    url: http://<host>:8100/mcp\n```\n\nIf the client shares the Compose network, use the service name and internal port:\n\n```yaml\nmcp_servers:\n  caldav:\n    url: http://caldav-mcp:8100/mcp\n```\n\nFor clients that launch local `stdio` servers, prefer the npm command from\n[Quick start](#quick-start). If a desktop client cannot find `npx`, use the absolute\npath reported by `command -v npx` on macOS/Linux or `where npx` on Windows.\n\n#### Claude Desktop\n\nAdd the [Quick start](#quick-start) JSON under `mcpServers` in\n`claude_desktop_config.json`, then completely restart Claude Desktop. Open the file\nthrough **Settings -> Developer -> Edit Config** instead of assuming its location.\n\n#### Claude Code\n\n[Claude Code](https://code.claude.com/docs/en/mcp) can add the same `stdio` server at\nuser scope:\n\n```sh\nclaude mcp add --transport stdio --scope user \\\n  --env CALDAV_USERNAME=user@example.com \\\n  --env CALDAV_PASSWORD=xxxx-xxxx-xxxx-xxxx \\\n  icloud-calendar -- npx --yes @lukegskw/caldav-mcp@latest\n```\n\nThis command places the values in Claude's MCP configuration. Avoid running it where\nshell history is shared or retained insecurely.\n\n#### Codex\n\nCodex can add the server to its shared CLI and IDE configuration:\n\n```sh\ncodex mcp add icloud-calendar \\\n  --env CALDAV_USERNAME=user@example.com \\\n  --env CALDAV_PASSWORD=xxxx-xxxx-xxxx-xxxx \\\n  -- npx --yes @lukegskw/caldav-mcp@latest\n```\n\nRun `codex mcp list` to verify it. For finer control, use the\n[official Codex MCP configuration](https://developers.openai.com/codex/mcp/) in\n`~/.codex/config.toml` or a project-scoped `.codex/config.toml`.\n\n#### Gemini CLI\n\nFollowing the [Gemini CLI MCP configuration](https://geminicli.com/docs/tools/mcp-server/),\nadd the server under `mcpServers` in `~/.gemini/settings.json` (user scope) or the\nproject's `.gemini/settings.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"icloud-calendar\": {\n      \"command\": \"npx\",\n      \"args\": [\"--yes\", \"@lukegskw/caldav-mcp@latest\"],\n      \"env\": {\n        \"CALDAV_USERNAME\": \"user@example.com\",\n        \"CALDAV_PASSWORD\": \"xxxx-xxxx-xxxx-xxxx\"\n      }\n    }\n  }\n}\n```\n\n#### Claude Desktop (Docker, stdio alternative)\n\nClaude Desktop launches local `stdio` servers as subprocesses. Running the published\ncontainer this way keeps the app-specific password on the client machine and opens no\nnetwork port, which matches the transport guidance in [Limitations](#limitations).\n\nAdd the server to `claude_desktop_config.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"icloud-calendar\": {\n      \"command\": \"/absolute/path/to/docker\",\n      \"args\": [\n        \"run\",\n        \"-i\",\n        \"--rm\",\n        \"--env-file\",\n        \"/absolute/path/to/caldav-mcp.env\",\n        \"-e\",\n        \"CALDAV_PROVIDER=icloud\",\n        \"-e\",\n        \"CALDAV_MCP_TRANSPORT=stdio\",\n        \"ghcr.io/lukegskw/caldav-mcp@sha256:<digest>\"\n      ]\n    }\n  }\n}\n```\n\n`-i` is required. Without an attached stdin the client cannot speak MCP to the\ncontainer. `--rm` removes the container once the client stops it.\n\nSupply credentials through `--env-file` rather than `-e`. Arguments passed to\n`docker run` are visible in the host process list; the contents of an env file are not.\nThe file holds the variables described in [Configuration](#configuration):\n\n```\nCALDAV_USERNAME=user@example.com\nCALDAV_PASSWORD=xxxx-xxxx-xxxx-xxxx\n```\n\nPin the image by digest instead of `latest`, so that restarting the client cannot\nsilently start a different version:\n\n```\ndocker pull ghcr.io/lukegskw/caldav-mcp:latest\ndocker images --digests ghcr.io/lukegskw/caldav-mcp\n```\n\nRestart Claude Desktop completely after editing the configuration file.\n\n##### Windows\n\nWhen Claude Desktop is installed from the Microsoft Store, Windows redirects\n`%APPDATA%\\Claude` into the package container and the file lives at:\n\n```\n%LOCALAPPDATA%\\Packages\\Claude_<package-id>\\LocalCache\\Roaming\\Claude\\claude_desktop_config.json\n```\n\nIn that case `dir %APPDATA%\\Claude` reports nothing. Server logs are written next to the\nconfiguration file, in `logs\\mcp-server-<server-name>.log`.\n\nUse the absolute path to `docker.exe`, because `PATH` inside the package container is\nnot reliable. `where docker` prints it, typically\n`C:\\Program Files\\Docker\\Docker\\resources\\bin\\docker.exe`. Backslashes must be escaped\nin JSON.\n\nConfiguration formats differ between MCP clients. Consult the client's documentation\nfor its exact schema and reload or restart it after changing the server definition.\n\n## Verification\n\nCheck the container state and logs:\n\n```sh\ndocker compose -f compose.example.yaml ps\ndocker compose -f compose.example.yaml logs caldav-mcp\n```\n\nThe container should report `healthy`. The TCP healthcheck validates the server process,\nnot iCloud credentials.\n\nRun the repository verification suite:\n\n```sh\npnpm install --frozen-lockfile\npnpm format:check\npnpm lint\npnpm typecheck\npnpm test:unit\npnpm test:integration\npnpm build\npnpm test:package\npnpm test:distribution\n```\n\nFinally, connect with an MCP client and confirm that all six tools are listed. Before a\nrelease, run the dedicated [iCloud manual validation](docs/icloud-manual-test.md) against\na test calendar.\n\n## Limitations\n\n- One iCloud account is configured per server process or container.\n- The Streamable HTTP endpoint has no authentication in the current release. Restrict it\n  to a trusted LAN, VPN, or private container network; do not expose it directly to the\n  internet.\n- Individual recurrence occurrences are read-only. Updating or deleting the complete\n  series is supported.\n- Only `ACTION:DISPLAY` alarms are created.\n- Individual iCalendar resources are limited to 5 MiB.\n- Event list ranges are limited to 366 days and pages to 500 results.\n- Events may contain at most 20 alarms.\n- Attendee scheduling is outside the current scope.\n- Providers other than iCloud are not officially supported.\n\nSee [troubleshooting](docs/troubleshooting.md) for discovery, authentication, ETag, and\nApple extension guidance. Review [SECURITY.md](SECURITY.md) before reporting a security\nissue or attaching diagnostics.\n\n## Contributing\n\nContributions are welcome. Before opening a pull request:\n\n```sh\npnpm install --frozen-lockfile\npnpm format:check\npnpm lint\npnpm typecheck\npnpm test\npnpm build\ndocker buildx build --load -t caldav-mcp:test .\n```\n\nChanges to CalDAV writes or iCalendar serialization must preserve ETag checks, opaque\nresource boundaries, unknown properties, recurrence exceptions, and alarms omitted from\npatches. TypeScript changes must continue to satisfy the rules in\n[`.codex/rules/typescript.md`](.codex/rules/typescript.md).\n\n## Releasing\n\nReleases are version-driven and automated from `main` so that a partial registry outage\ncan be retried without publishing a second npm version.\n\n1. Prepare the new version with `pnpm release:prepare X.Y.Z`. This synchronizes the npm,\n   MCP Registry, and Gemini metadata.\n2. Run the verification suite, including `pnpm test:distribution`.\n3. Commit and push the release changes to `main`.\n4. The release workflow validates the commit and creates the matching `vX.Y.Z` tag\n   automatically before publishing.\n\nThe release workflow validates the versions, tests the packed npm artifact, and\npublishes the exact, minor-series, and `latest` container tags together with the npm\npackage, MCP Registry entry, and GitHub release. Prereleases receive only their exact\ncontainer tag. Gemini can discover the tagged extension without another per-release\nedit. A rerun skips matching artifacts that already exist and resumes the missing\nsteps. See [the container release strategy](docs/container-release-strategy.md) for the\nCI and tagging decisions.\n\n## License\n\nMIT. See [LICENSE](LICENSE).\n",
  "bytes": 20784,
  "sha": "25d233a1b36e6baf2a00b6445b748308a06bb88a04b8439efa9449df53e47a7b",
  "repo_slug": "lukegskw/caldav-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/plg_lukegskw_caldav_mcp_26b3c916/readme"
}