icloud-calendar-mcp

<p align="center"> <img src="assets/logo.svg" width="120" alt="iCloud Calendar MCP logo"> </p>

<h1 align="center">iCloud Calendar MCP</h1>

<p align="center"> An MCP server for managing iCloud Calendar. </p>

<p align="center"> <strong>English</strong> · <a href="docs/README.zh-CN.md">简体中文</a> </p>

<p align="center"> <a href="https://www.npmjs.com/package/icloud-calendar-mcp"><img alt="npm version" src="https://img.shields.io/npm/v/icloud-calendar-mcp"></a> <a href="https://www.npmjs.com/package/icloud-calendar-mcp"><img alt="npm downloads" src="https://img.shields.io/npm/dm/icloud-calendar-mcp"></a> <a href="https://github.com/IceyWu/icloud-calendar-mcp/actions/workflows/ci.yml"><img alt="CI status" src="https://github.com/IceyWu/icloud-calendar-mcp/actions/workflows/ci.yml/badge.svg"></a> <a href="https://www.npmjs.com/package/icloud-calendar-mcp"><img alt="Node.js version" src="https://img.shields.io/node/v/icloud-calendar-mcp"></a> <a href="LICENSE"><img alt="MIT license" src="https://img.shields.io/npm/l/icloud-calendar-mcp"></a> </p>

Setup

Requirements:

• Node.js 22.13 or later
• Your Apple Account email
• An Apple app-specific password

Add the server to your MCP client:

{
  "mcpServers": {
    "icloud-calendar": {
      "command": "npx",
      "args": ["-y", "icloud-calendar-mcp"],
      "env": {
        "ICLOUD_USERNAME": "you@example.com",
        "ICLOUD_APP_PASSWORD": "xxxx-xxxx-xxxx-xxxx"
      }
    }
  }
}

Use an app-specific password, not your Apple Account password.

Tools

Tool	Purpose
list_calendars	List calendars
list_events	List events in a time range
get_event	Get an event
create_event	Create an event
update_event	Update an event
delete_event	Delete an event
find_conflicts	Find overlapping events
free_busy	Return busy time ranges

Events can include time zones, all-day dates, recurrence rules, alarms, locations, descriptions, URLs, and attendees.

Example requests

Once the server is connected, you can ask your MCP client:

Show my calendars.

What is on my calendar next week in Asia/Shanghai time?

Add a project review to my Work calendar tomorrow from 2:00 PM to 3:00 PM, with a reminder 15 minutes before.

Do I have any conflicts on Friday between 9:00 AM and noon?

Move the project review to 4:00 PM and change the location to Meeting Room B.

Add an all-day event called “Company holiday” on October 1.

Delete the project review event.

For ambiguous requests, include the calendar, date, time, and time zone when possible.

Behavior

• All-day event end dates are exclusive. A one-day event on August 18 uses 2026-08-18 to 2026-08-19.
• Create, update, and delete operations accept a request_id for safe retries.
• Concurrent changes are detected with ETags.
• Whole recurring series can be updated or deleted. Unsupported occurrence-level changes return an error instead of modifying the series.

See tool contracts for complete inputs, outputs, and error codes.

HTTP

stdio is the default transport. Streamable HTTP is optional:

ICLOUD_MCP_TRANSPORT=http \
ICLOUD_MCP_HTTP_TOKEN='replace-with-a-long-random-token' \
ICLOUD_MCP_HTTP_PORT=3000 \
npx -y icloud-calendar-mcp

HTTP mode requires a bearer token and listens on loopback by default. See security before exposing it through a proxy.

Development

pnpm install
pnpm check

See architecture, contributing, and releasing.

License

MIT