Icloud Calendar MCP

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.