iCloud Calendar MCP Server

Build npm PyPI License MCP Registry Tests Security

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.

Features

MCP Tools

MCP Resources

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 17+ (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 from GitHub Releases
curl -LO https://github.com/icloud-calendar-mcp/icloud-calendar-mcp/releases/latest/download/icloud-calendar-mcp-3.1.0-all.jar

# Run
java -jar icloud-calendar-mcp-3.1.0-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-3.1.0-all.jar

Configuration

Set your iCloud credentials as environment variables:

export ICLOUD_USERNAME="[email protected]"
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": "[email protected]",
        "ICLOUD_PASSWORD": "your-app-specific-password"
      }
    }
  }
}

{
  "mcpServers": {
    "icloud-calendar": {
      "command": "uvx",
      "args": ["icloud-calendar-mcp"],
      "env": {
        "ICLOUD_USERNAME": "[email protected]",
        "ICLOUD_PASSWORD": "your-app-specific-password"
      }
    }
  }
}

{
  "mcpServers": {
    "icloud-calendar": {
      "command": "java",
      "args": ["-jar", "/path/to/icloud-calendar-mcp-3.1.0-all.jar"],
      "env": {
        "ICLOUD_USERNAME": "[email protected]",
        "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

create_event

update_event

delete_event

Note — resolving an event by event_id: update_event and delete_event locate the target event in the current session's in-memory cache, which is populated by get_events (and by the create_event that created it). Within a session the usual flow — get_events → update_event/delete_event — works without any extra step. If you start a fresh session and want to act on an existing event, call get_events for its calendar first so the event is cached. There is no per-request server-side lookup by UID: iCloud rejects a CalDAV calendar-query UID prop-filter (HTTP 412), and an unfiltered query would return the entire calendar, so a stateless UID lookup is not practical.

Security

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

Security Controls

OWASP MCP Top 10 Coverage

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

Testing

The MCP server has 843 tests. The vendored icaldav-core iCalendar library has a further 1714 tests. 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="[email protected]" \
ICLOUD_PASSWORD="test-app-password" \
npx @mcp-use/inspector java -jar build/libs/icloud-calendar-mcp-3.1.0-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