Back to Directory/Productivity

org.onekash/icloud-calendar-mcp

MCP server for iCloud (Apple) Calendar access via CalDAV

ProductivityKotlinv3.0.0
View on GitHub

iCloud Calendar MCP Server

Build npm PyPI License MCP Registry Tests Security

A security-first MCP (Model Context Protocol) server that provides AI assistants with secure access to iCloud Calendar via CalDAV. Built with comprehensive 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

ToolDescriptionRead-OnlyDestructive
list_calendarsList all calendars from iCloud accountYesNo
get_eventsGet events within a date range from a calendarYesNo
create_eventCreate a new calendar eventNoNo
update_eventUpdate an existing eventNoNo
delete_eventDelete an event by IDNoYes

MCP Resources

ResourceDescription
calendar://calendarsBrowse available calendars

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 - 239 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

Installation

Choose your preferred installation method:

Option 1: npm (Recommended)

bash
npx @icloud-calendar-mcp/server

Option 2: Python (uvx)

bash
uvx icloud-calendar-mcp

Option 3: Direct JAR

bash
# Download from GitHub Releases
curl -LO https://github.com/icloud-calendar-mcp/icloud-calendar-mcp/releases/latest/download/icloud-calendar-mcp-1.0.0-all.jar

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

Option 4: Build from Source

bash
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-1.0.0-all.jar

Configuration

Set your iCloud credentials as environment variables:

bash
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:

PlatformConfig Path
macOS~/Library/Application Support/Claude/claude_desktop_config.json
Linux~/.config/claude/claude_desktop_config.json
Windows%APPDATA%\Claude\claude_desktop_config.json
<details open> <summary><strong>Using npm (Recommended)</strong></summary>
json
{
  "mcpServers": {
    "icloud-calendar": {
      "command": "npx",
      "args": ["@icloud-calendar-mcp/server"],
      "env": {
        "ICLOUD_USERNAME": "your-apple-id@icloud.com",
        "ICLOUD_PASSWORD": "your-app-specific-password"
      }
    }
  }
}
</details> <details> <summary><strong>Using uvx (Python)</strong></summary>
json
{
  "mcpServers": {
    "icloud-calendar": {
      "command": "uvx",
      "args": ["icloud-calendar-mcp"],
      "env": {
        "ICLOUD_USERNAME": "your-apple-id@icloud.com",
        "ICLOUD_PASSWORD": "your-app-specific-password"
      }
    }
  }
}
</details> <details> <summary><strong>Using JAR directly</strong></summary>
json
{
  "mcpServers": {
    "icloud-calendar": {
      "command": "java",
      "args": ["-jar", "/path/to/icloud-calendar-mcp-1.0.0-all.jar"],
      "env": {
        "ICLOUD_USERNAME": "your-apple-id@icloud.com",
        "ICLOUD_PASSWORD": "your-app-specific-password"
      }
    }
  }
}
</details>

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

ParameterTypeRequiredDescription
calendar_idstringYesCalendar identifier
start_datestringYesStart date (YYYY-MM-DD)
end_datestringYesEnd date (YYYY-MM-DD)

create_event

ParameterTypeRequiredDescription
calendar_idstringYesTarget calendar
titlestringYesEvent title
start_timestringYesISO 8601 datetime or YYYY-MM-DD
end_timestringYesISO 8601 datetime or YYYY-MM-DD
descriptionstringNoEvent description
locationstringNoEvent location
is_all_daybooleanNoAll-day event flag

update_event

ParameterTypeRequiredDescription
event_idstringYesEvent to update
titlestringNoNew title
start_timestringNoNew start time
end_timestringNoNew end time
descriptionstringNoNew description
locationstringNoNew location

delete_event

ParameterTypeRequiredDescription
event_idstringYesEvent to delete

Security

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

Security Controls

ControlImplementation
Credential StorageEnvironment variables only, never logged or exposed
Input ValidationAll inputs validated (calendar IDs, dates, times, text fields)
SSRF ProtectionBlocks internal IPs, localhost, and dangerous URI schemes
Rate LimitingSliding window: 60 reads/min, 20 writes/min
Error HandlingPasswords, tokens, paths, emails sanitized from errors
Injection PreventionICS content properly escaped, command injection tested
ReDoS ProtectionAll regex patterns tested for catastrophic backtracking
Unicode SecurityHomoglyph, normalization, and encoding bypass protection

OWASP MCP Top 10 Coverage

RiskMitigationTests
MCP01: Token MismanagementCredentials masked in logs/errors, secure storage14
MCP02: Privilege EscalationFixed tool set, no dynamic registration5
MCP03: Tool Argument InjectionInput validation, parameterized operations8
MCP04: Sensitive Data ExposureError sanitization, credential masking10
MCP05: Command InjectionInput treated as data, not executed3
MCP06: Prompt InjectionMalicious text stored as data, not interpreted3
MCP08: Insecure LoggingRate limiting, sensitive data sanitization31
MCP09: Resource ExhaustionRate limiting, input size limits, DoS protection25
MCP10: Context Over-sharingIsolated state, no cross-request data leakage3

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

Testing

The server includes 555 comprehensive tests across 26 test suites:

bash
./gradlew test

Test Coverage

CategoryTestsDescription
Security239Adversarial inputs, OWASP MCP Top 10, ReDoS, Unicode
CalDAV Protocol105XML parsing, HTTP client, models
ICS Parsing48RFC 5545 compliance, edge cases
Input Validation39All parameter validation rules
Error Handling32Secure error responses
Integration26End-to-end tool execution
Service Layer21Calendar operations, caching
Rate Limiting15Concurrent access, window reset
Cancellation12Operation cancellation, cleanup
Logging9MCP logging compliance
Progress9Progress reporting

Security Test Categories

CategoryTestsCoverage
Adversarial Inputs53SQL/NoSQL injection, XSS, path traversal
Unicode Security38Homoglyphs, normalization, RTL override
Logger Security31Log injection, credential sanitization
OWASP MCP Risks29MCP01-10 specific attack vectors
Progress Security27Token enumeration, injection
ReDoS Protection25Catastrophic backtracking, resource exhaustion
Cancellation Security22Replay attacks, race conditions
Credential Security14Token masking, secure storage

Running Specific Tests

bash
# 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

text
+------------------------------------------------------------------+
|                    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            |  |  (ical4j)         |  |  (RFC 5545)    |  |
|  +-------------------+  +-------------------+  +----------------+  |
|                                                                    |
|  +-------------------+  +-------------------+                      |
|  | ICloudXml         |  |  Credential       |                      |
|  | Parser            |  |  Manager          |                      |
|  +-------------------+  +-------------------+                      |
+------------------------------------------------------------------+
                              |
                              v
+------------------------------------------------------------------+
|                    iCloud CalDAV API                               |
|                    caldav.icloud.com                               |
+------------------------------------------------------------------+

Development

Build

bash
# Build
./gradlew build

# Build fat JAR
./gradlew fatJar

# Run tests
./gradlew test

# Clean build
./gradlew clean build

Project Structure

text
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
├── ics/                    # ICS format handling
│   ├── IcsParser.kt        # Parse iCalendar data
│   └── IcsBuilder.kt       # Generate iCalendar data
├── service/                # Business logic
│   ├── CalendarService.kt
│   └── EventCache.kt
├── 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

bash
ICLOUD_USERNAME="test@icloud.com" \
ICLOUD_PASSWORD="test-app-password" \
npx @mcp-use/inspector java -jar build/libs/icloud-calendar-mcp-1.0.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

Learn More

Best MCP Servers for Productivity: Tasks, Calendar, and NotesMCP servers let you ask Claude to schedule meetings, create tasks, and search notes without switching apps. This guide covers the best options across MCPFind's 13 productivity and 128 communication servers, with auth methods and setup complexity for each.Read articleHow to Connect Notion to AI Agents With MCPConnecting Notion to an AI agent through MCP lets you ask questions about your notes, create pages, and update databases without copy-pasting. This beginner-friendly guide walks through setup and shows what else is possible in the productivity category.Read article