iCloud Calendar MCP Server

An MCP (Model Context Protocol) server that gives AI assistants access to iCloud Calendar via CalDAV, with security controls aligned with the OWASP MCP Top 10.

[!CAUTION] Never use your main Apple ID password. This server requires an app-specific password which can be revoked independently without affecting your Apple ID.

Why this server

• Portable CalDAV. Runs anywhere a JVM runs. It does not depend on macOS, AppleScript, or Calendar.app.
• Durable event handles. get_events and create_event return an opaque handle that references an event across sessions and process restarts, so editing or deleting one needs no re-listing.
• Correct recurrence. A series expands into one result per occurrence in the range, and you can edit or delete a single occurrence, this-and-future, or the whole series.
• Bounded responses. Date-span and event-count caps return a clear, structured error instead of a silently truncated response.
• Security aligned with the OWASP MCP Top 10, backed by a dedicated test suite.
• Published on the MCP Registry, npm, and PyPI.

Features

MCP Tools

MCP Resources

MCP Prompts

User-initiated templates that guide Claude through a multi-step task:

Security Features

• Credential Protection - Environment variables only, never in code or config
• Input Validation - All parameters validated with SSRF protection
• Rate Limiting - 60 reads/min, 20 writes/min per MCP specification
• Secure Error Handling - No sensitive data leakage in error messages
• OWASP MCP Top 10 Compliance - 282 security tests covering all major risks
• ReDoS Protection - All regex patterns tested against catastrophic backtracking
• Unicode Security - Protection against homoglyph and encoding attacks

Quick Start

Prerequisites

• Java 21+ (for all installation methods)
• iCloud account with app-specific password

Installation

Choose your preferred installation method:

[!IMPORTANT] Every option runs the same Java build. Java 21 or newer must be on your PATH, including for npx and uvx. Those wrappers download and launch the JAR; they do not replace the JVM.

Option 1: npm (Recommended)

npx @icloud-calendar-mcp/server

Option 2: Python (uvx)

uvx icloud-calendar-mcp

Option 3: Direct JAR

# Download the latest release (version-agnostic name, always resolves)
curl -LO https://github.com/icloud-calendar-mcp/icloud-calendar-mcp/releases/latest/download/icloud-calendar-mcp-all.jar

# Run
java -jar icloud-calendar-mcp-all.jar

Option 4: Build from Source

git clone https://github.com/icloud-calendar-mcp/icloud-calendar-mcp.git
cd icloud-calendar-mcp
./gradlew fatJar
java -jar build/libs/icloud-calendar-mcp-*-all.jar

Configuration

Set your iCloud credentials as environment variables:

export ICLOUD_USERNAME="your-apple-id@icloud.com"
export ICLOUD_PASSWORD="your-app-specific-password"

Security Note: Use an app-specific password, not your main Apple ID password.

Claude Desktop Integration

Add to your Claude Desktop configuration:

{
  "mcpServers": {
    "icloud-calendar": {
      "command": "npx",
      "args": ["@icloud-calendar-mcp/server"],
      "env": {
        "ICLOUD_USERNAME": "your-apple-id@icloud.com",
        "ICLOUD_PASSWORD": "your-app-specific-password"
      }
    }
  }
}

{
  "mcpServers": {
    "icloud-calendar": {
      "command": "uvx",
      "args": ["icloud-calendar-mcp"],
      "env": {
        "ICLOUD_USERNAME": "your-apple-id@icloud.com",
        "ICLOUD_PASSWORD": "your-app-specific-password"
      }
    }
  }
}

{
  "mcpServers": {
    "icloud-calendar": {
      "command": "java",
      "args": ["-jar", "/path/to/icloud-calendar-mcp-all.jar"],
      "env": {
        "ICLOUD_USERNAME": "your-apple-id@icloud.com",
        "ICLOUD_PASSWORD": "your-app-specific-password"
      }
    }
  }
}

Usage Examples

Once configured, you can ask Claude:

• "What's on my calendar this week?"
• "Create a meeting with John tomorrow at 2pm"
• "Show me all my calendars"
• "Delete the dentist appointment on Friday"
• "Move my 3pm meeting to 4pm"

Tool Parameters

list_calendars

No parameters required.

get_events

Behavior to know about:

• UTC day boundaries. start_date and end_date select whole UTC calendar days: start_date at 00:00 UTC through the end of end_date in UTC. Timed events return UTC startTime/endTime instants; all-day events return a plain YYYY-MM-DD. To resolve a user's day in another timezone, request one extra day on each side and keep the events whose start, converted to that zone, falls on the wanted day; all-day events are floating dates and need no conversion.
• Limits. The range is capped at 366 days, and end_date must not precede start_date. The response is capped at 1000 events, and a single recurring series that expands to too many occurrences is rejected. If you hit a cap, query a week or a month at a time.
• Recurring series. Each occurrence in the range is returned as its own result, carrying its own handle and a recurrenceId that identifies the instance.
• Read-after-write. iCloud does not guarantee immediate visibility, so an event created moments ago can be missing from the next get_events for a short window. This is CDN indexing lag, not a deletion, so do not recreate it.

Each result includes uid, handle, summary, isAllDay, and startTime/endTime (timed) or startDate/endDate (all-day), plus any of description, location, rrule, recurrenceId, status, url, categories, priority, organizer, attendeeCount that are set.

create_event

update_event

Only the fields you pass are changed.