icloud-calendar-mcp

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.

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.

Related MCP server: iCloud CalDAV MCP Connector

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:

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.

delete_event

Referencing an event

get_events and create_event return two identifiers for each event: a uid and an opaque handle. Pass the handle to update_event and delete_event. It is self-contained and works from a fresh process, so the normal flow is get_events (or create_event) to obtain the handle, then update_event/delete_event with it. No extra lookup step is needed across sessions.

A bare uid is also accepted, but only for an event fetched earlier in the same session, where it resolves through a short-lived in-memory cache. There is no stateless server-side lookup by UID: iCloud rejects a CalDAV calendar-query UID prop-filter (HTTP 412), and an unfiltered query would return the whole calendar. Prefer the handle.

A handle carries the event's ETag. If the event changed elsewhere since the handle was issued, the edit reports a conflict rather than overwriting the newer version; re-run get_events for a fresh handle and retry. On success, update_event returns a refreshed handle carrying the new ETag, so use that one for the next edit in a chain.

Editing recurring events

get_events returns one result per occurrence of a recurring series, each with its own handle. When you edit or delete an occurrence handle, set scope:

• this_occurrence: change or cancel only that instance.

• this_and_future: that instance and every later one.

• all_events: the whole series.

scope is required when the handle points at one occurrence of a series. The operation is rejected without it, so a single-occurrence edit never changes the whole series by accident. Omit scope for standalone events. rrule, rdates, and exdates cannot be combined with this_occurrence or this_and_future.

Alarms

create_event and update_event take an alarms array. Each entry is an object:

On update_event, omit alarms to keep the existing ones, pass an empty array to clear them, or pass a list to replace them.

Troubleshooting

A new event does not appear right away. iCloud does not guarantee immediate visibility, so a just-created event can be missing from the next get_events for a short window (CDN indexing lag). The create_event success response is authoritative. Do not recreate the event.

get_events returns a size or count error. The range is too wide. Query a week or a month at a time; the response is capped at 1000 events.

Authentication fails. Use an app-specific password, not your Apple ID password, and set ICLOUD_USERNAME to your full iCloud email address.

Not sure which calendar_id to use. Call list_calendars and use the id of the calendar you want.

A recurring edit was rejected or changed every instance. Set scope (see Editing recurring events): an occurrence handle needs this_occurrence, this_and_future, or all_events.

Times look shifted by your timezone. get_events uses UTC day boundaries (see get_events). Pass timezone when creating timed events, and use the extra-day approach to resolve a local day.

Security

This server is designed with security as a primary concern, following the OWASP MCP Top 10 guidelines.

Privacy

The server talks only to your machine (over STDIO) and to iCloud (caldav.icloud.com). It has no telemetry and sends your calendar data nowhere else. Credentials come from environment variables and are never logged.

Security Controls

OWASP MCP Top 10 Coverage

See SECURITY.md for full security documentation and vulnerability disclosure process.

Testing

Tests live in two places: the MCP server module and the vendored icaldav-core iCalendar library. Both run with:

./gradlew test

Test Coverage (MCP server)

Security Test Categories

Running Specific Tests

# All tests
./gradlew test

# Security tests only
./gradlew test --tests "*SecurityTest*"
./gradlew test --tests "AdversarialTest"

# OWASP MCP specific tests
./gradlew test --tests "OwaspMcpSecurityTest"

# Unicode security tests
./gradlew test --tests "UnicodeSecurityTest"

# ReDoS protection tests
./gradlew test --tests "ReDoSSecurityTest"

# CalDAV tests
./gradlew test --tests "*CalDav*"

# ICS tests
./gradlew test --tests "*Ics*"

Architecture

+------------------------------------------------------------------+
|                    MCP Server (STDIO Transport)                    |
|                                                                    |
|  +----------------+  +----------------+  +----------------------+  |
|  | Rate Limiter   |  |   Input        |  |  Secure Error        |  |
|  | 60r/20w/min    |  |  Validator     |  |  Handler             |  |
|  +----------------+  +----------------+  +----------------------+  |
|                                                                    |
|  +----------------+  +----------------+  +----------------------+  |
|  | MCP Logger     |  | Cancellation   |  |  Progress            |  |
|  | (RFC 5424)     |  | Manager        |  |  Reporter            |  |
|  +----------------+  +----------------+  +----------------------+  |
|                                                                    |
|  Tools: list_calendars | get_events | create_event |               |
|         update_event | delete_event                                |
|                                                                    |
|  Resources: calendar://calendars                                   |
+------------------------------------------------------------------+
                              |
                              v
+------------------------------------------------------------------+
|                      CalendarService                               |
|  Orchestrates CalDAV operations, caches calendar metadata          |
+------------------------------------------------------------------+
                              |
                              v
+------------------------------------------------------------------+
|                      CalDAV Client Layer                           |
|                                                                    |
|  +-------------------+  +-------------------+  +----------------+  |
|  | OkHttpCalDav      |  |  IcsParser        |  |  IcsBuilder    |  |
|  | Client            |  |  (icaldav-core)   |  |  (icaldav-core)|  |
|  +-------------------+  +-------------------+  +----------------+  |
|                                                                    |
|  +-------------------+  +-------------------+  +----------------+  |
|  | ICloudXml         |  |  IcsPatcher       |  |  EtagUtils     |  |
|  | Parser            |  |  (event edits)    |  |  (RFC 7232)    |  |
|  +-------------------+  +-------------------+  +----------------+  |
|                                                                    |
|  +-------------------+                                             |
|  | Credential        |                                             |
|  | Manager           |                                             |
|  +-------------------+                                             |
+------------------------------------------------------------------+
                              |
                              v
+------------------------------------------------------------------+
|                    iCloud CalDAV API                               |
|                    caldav.icloud.com                               |
+------------------------------------------------------------------+

Development

Build

# Build
./gradlew build

# Build fat JAR
./gradlew fatJar

# Run tests
./gradlew test

# Clean build
./gradlew clean build

Project Structure

src/main/kotlin/org/onekash/mcp/calendar/
├── Main.kt                 # MCP server entry point
├── caldav/                 # CalDAV protocol implementation
│   ├── CalDavClient.kt     # Client interface
│   ├── CalDavModels.kt     # Domain models
│   ├── OkHttpCalDavClient.kt
│   ├── ICloudXmlParser.kt
│   └── EtagUtils.kt        # RFC 7232 ETag normalization
├── ics/                    # ICS format handling (via icaldav-core)
│   ├── IcsParser.kt        # Parse iCalendar data
│   ├── IcsBuilder.kt       # Generate iCalendar data
│   └── IcsPatcher.kt       # Patch existing events (CRLF-safe)
├── service/                # Business logic
│   └── CalendarService.kt  # CalDAV orchestration + event cache
├── security/               # Security controls
│   └── CredentialManager.kt
├── validation/             # Input validation
│   └── InputValidator.kt
├── error/                  # Error handling
│   └── SecureErrorHandler.kt
├── ratelimit/              # Rate limiting
│   └── RateLimiter.kt
├── logging/                # MCP logging
│   └── McpLogger.kt
├── progress/               # Progress reporting
│   └── ProgressReporter.kt
└── cancellation/           # Operation cancellation
    └── CancellationManager.kt

Testing with MCP Inspector

ICLOUD_USERNAME="test@icloud.com" \
ICLOUD_PASSWORD="test-app-password" \
npx @mcp-use/inspector java -jar build/libs/icloud-calendar-mcp-*-all.jar

Contributing

We welcome contributions! Please see CONTRIBUTING.md for guidelines.

Security Issues

For security vulnerabilities, please see SECURITY.md for our responsible disclosure process. Do not open public issues for security vulnerabilities.

License

This project is licensed under the Apache License 2.0 - see the LICENSE file for details.

Acknowledgments

• Model Context Protocol by Anthropic

• MCP Kotlin SDK by Anthropic & JetBrains

• ical4j for low-level ICS parsing (via the bundled icaldav-core library)

• OkHttp for HTTP client

• OWASP MCP Top 10 for security guidance