iCloud Calendar MCP
An MCP server for managing iCloud Calendar.
English · 简体中文
Setup
Requirements:
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.
| 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
See architecture, contributing, and releasing.
License
MIT