icloud-calendar-mcp — Claude Code MCP server: what it does and setup
Connects AI coding assistants to iCloud Calendar via CalDAV. Lets agents fetch schedules, create events, and edit recurring meetings from chat.
claude mcp add icloud-calendar-mcp -e ICLOUD_USERNAME=<ICLOUD_USERNAME> -e ICLOUD_PASSWORD=<ICLOUD_PASSWORD> -- npx -y @icloud-calendar-mcp/serverWhat icloud-calendar-mcp does
This server connects tools like Claude Code directly to Apple Calendar through standard CalDAV. It operates independently of macOS, Calendar.app, or AppleScript. Assistants receive tools to inspect available calendars, query date spans, insert appointments, and modify existing entries. Recurring events expand into individual occurrences, letting the model update an entire series or a single date.
Under the hood, the server runs a Java application wrapped for npm and Python distribution. Java 21 or newer must be installed on your PATH, or the wrapper fails immediately upon start.
Authentication strictly requires an app-specific password rather than your primary Apple ID credentials. The server enforces rate limits of 60 reads and 20 writes per minute, alongside input validation against SSRF and ReDoS vulnerabilities.
What it helps with
- inspect iCloud calendar schedules over specified date ranges
- reschedule or cancel single instances of recurring meetings
- detect overlapping appointments using built-in prompts
- add new events directly to Apple Calendar from terminal chats
Example prompts for the agent
- List all events on my schedule for tomorrow
- Move my 3 PM appointment to 4 PM on Friday
- Check my calendar for conflicts this Thursday
How to install icloud-calendar-mcp
Platform CLI
claude mcp add icloud-calendar-mcp -e ICLOUD_USERNAME=<ICLOUD_USERNAME> -e ICLOUD_PASSWORD=<ICLOUD_PASSWORD> -- npx -y @icloud-calendar-mcp/serverReplace <…> with your own values
Platform CLI
codex mcp add icloud-calendar-mcp --env ICLOUD_USERNAME=<ICLOUD_USERNAME> --env ICLOUD_PASSWORD=<ICLOUD_PASSWORD> -- npx -y @icloud-calendar-mcp/serverReplace <…> with your own values
Config file
{
"mcpServers": {
"icloud-calendar-mcp": {
"command": "npx",
"args": [
"-y",
"@icloud-calendar-mcp/server"
],
"env": {
"ICLOUD_USERNAME": "<ICLOUD_USERNAME>",
"ICLOUD_PASSWORD": "<ICLOUD_PASSWORD>"
}
}
}
}Replace <…> with your own values
Config file
{
"servers": {
"icloud-calendar-mcp": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"@icloud-calendar-mcp/server"
],
"env": {
"ICLOUD_USERNAME": "<ICLOUD_USERNAME>",
"ICLOUD_PASSWORD": "<ICLOUD_PASSWORD>"
}
}
}
}Replace <…> with your own values
Platform CLI
gemini mcp add -e ICLOUD_USERNAME=<ICLOUD_USERNAME> -e ICLOUD_PASSWORD=<ICLOUD_PASSWORD> icloud-calendar-mcp npx -y @icloud-calendar-mcp/serverReplace <…> with your own values
Step by step, with commands for each platform: How to add an MCP server to Claude Code, Codex, Cursor, VS Code, Gemini CLI and more
Questions about icloud-calendar-mcp
How to install icloud-calendar-mcp in Claude Code?
Run claude mcp add icloud-calendar-mcp -e ICLOUD_USERNAME=<ICLOUD_USERNAME> -e ICLOUD_PASSWORD=<ICLOUD_PASSWORD> -- npx -y @icloud-calendar-mcp/server. Replace the placeholders with your Apple ID email and an app-specific password.
What does icloud-calendar-mcp do?
It provides CalDAV tools for AI assistants to view calendars, check schedules, create meetings, and update recurring entries in iCloud.
Does icloud-calendar-mcp require macOS?
No, it does not rely on macOS or AppleScript. It runs anywhere Java 21 is available by communicating directly over standard CalDAV.
