Icloud Calendar

What the icloud-calendar MCP server does

The icloud-calendar MCP server exposes Apple iCloud Calendar through the Model Context Protocol. It is intended for MCP clients that need calendar data or calendar mutations without implementing CalDAV operations themselves. The server can enumerate calendars, query events within a time range, retrieve a specific event, and create, update, or delete events.

Scheduling-oriented queries are also supported. find_conflicts identifies overlapping events, while free_busy returns busy time ranges. Event data may include time zones, all-day dates, recurrence rules, alarms, locations, descriptions, URLs, and attendees.

How it works

The server uses the Apple Account email and an Apple app-specific password to access iCloud Calendar. The app-specific password is required instead of the normal Apple Account password. MCP clients start the package with npx, using the configured credentials as environment variables.

stdio is the default transport. Streamable HTTP can be selected with an environment variable and configured to use a port and bearer token. HTTP mode listens on loopback by default; deployments that place it behind a proxy should review the project’s security guidance before exposing it beyond the local machine.

Write operations accept a request_id, which allows clients to retry safely. Concurrent modifications are checked with ETags. Updates and deletions can apply to an entire recurring series, but occurrence-level changes that are not supported return an error rather than changing the series.

Setup and configuration

Node.js 22.13 or newer is required. Configure the server in the MCP client with the icloud-calendar-mcp package and provide ICLOUD_USERNAME for the Apple Account email and ICLOUD_APP_PASSWORD for the app-specific password. A typical stdio configuration invokes npx -y icloud-calendar-mcp.

For HTTP transport, set ICLOUD_MCP_TRANSPORT=http, provide ICLOUD_MCP_HTTP_TOKEN with a long random token, and optionally set ICLOUD_MCP_HTTP_PORT to choose the listening port. The HTTP token is required when HTTP mode is enabled.

Tools and capabilities

The icloud-calendar MCP server provides these tools:

• list_calendars lists available calendars.
• list_events finds events in a specified time range.
• get_event retrieves an individual event.
• create_event adds an event.
• update_event changes an event.
• delete_event removes an event.
• find_conflicts finds overlapping events.
• free_busy returns busy intervals.

When making date-related requests, specify the calendar, date, time, and time zone when possible. All-day event end dates are exclusive: a one-day event on August 18 uses August 18 as its start and August 19 as its end.

Limitations and notes

The server requires access to an Apple Account with an app-specific password and does not use the account’s regular password. Occurrence-level edits for recurring events are unsupported; requests for those changes return an error. All-day date ranges also require clients to account for exclusive end dates. Complete input, output, and error details are provided in the project’s tool-contract documentation.