About icloud-calendar
icloud-calendar is an MCP server for managing Apple iCloud Calendar, intended for people who want to handle calendar data through an MCP client. It supports event operations, conflict checks, and busy-time queries, including recurrence and time-zone details.
Key features
- 01List calendars and events
- 02Create, retrieve, update, and delete events
- 03Detect scheduling conflicts
- 04Query busy time ranges
- 05Handle recurrence and time-zone details
Use cases
- 01Review events within a date range
- 02Schedule or revise a calendar event
- 03Check for overlapping appointments
MCP support
Exposes iCloud Calendar operations to MCP clients through tools for listing calendars and events, managing events, finding conflicts, and querying busy times. Supports stdio by default and optional Streamable HTTP.
Configuration
Local server config is the same for every client. Copy it into your client’s MCP config file.
npx -y icloud-calendar-mcpICLOUD_USERNAMEApple Account email addressICLOUD_APP_PASSWORDSecretApple app-specific password (never the Apple Account password)Local servers need a runtime on your machine (e.g. Node.js 18+). Config file locations differ by client; see your client’s docs.
Tools
Local servers expose tools only once running on your machine, and the maintainer has not provided a tool list.
Details
From the project README
iCloud Calendar MCP
An MCP server for managing iCloud Calendar.
English · 简体中文
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": "[email protected]",
"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-18to2026-08-19. - Create, update, and delete operations accept a
request_idfor 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
Comments
New to MCP?
From what the protocol is to installing your first server, these answers cover most first questions.
An open protocol that defines how AI applications connect to external tools and data in a uniform way. Clients talk to the model; MCP servers provide tools, resources and prompt templates. They exchange standard messages, so one server can be reused by many clients.