Skip to main content
Glama
icloud-calendar-mcp

icloud-calendar-mcp

by icloud-calendar-mcp
OverviewSchemaRelated ServersScoreDiscussions
Remote

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

Tool

Description

Read-Only

Destructive

list_calendars

List all calendars from iCloud account

Yes

No

get_events

Get events within a date range from a calendar

Yes

No

create_event

Create a new calendar event

No

No

update_event

Update an existing event

No

No

delete_event

Delete an event by ID

No

Yes

MCP Resources

Resource

Description

calendar://calendars

Browse 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 - 282 security tests covering all major risks

  • ReDoS Protection - All regex patterns tested against catastrophic backtracking

  • Unicode Security - Protection against homoglyph and encoding attacks

Related MCP server: iCloud CalDAV MCP Connector

Quick Start

Prerequisites

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="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:

Platform

Config Path

macOS

~/Library/Application Support/Claude/claude_desktop_config.json

Linux

~/.config/claude/claude_desktop_config.json

Windows

%APPDATA%\Claude\claude_desktop_config.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"
      }
    }
  }
}
{
  "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-3.1.0-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

Parameter

Type

Required

Description

calendar_id

string

Yes

Calendar identifier

start_date

string

Yes

Start date (YYYY-MM-DD)

end_date

string

Yes

End date (YYYY-MM-DD)

create_event

Parameter

Type

Required

Description

calendar_id

string

Yes

Target calendar

title

string

Yes

Event title

start_time

string

Cond.

ISO 8601 datetime (required for timed events)

end_time

string

Cond.

ISO 8601 datetime (required for timed events)

start_date

string

Cond.

Start date YYYY-MM-DD (required for all-day events)

end_date

string

Cond.

End date YYYY-MM-DD, inclusive (required for all-day events)

is_all_day

boolean

No

All-day event flag

description

string

No

Event description

location

string

No

Event location

timezone

string

No

IANA timezone (e.g., America/New_York)

rrule

string

No

Recurrence rule (e.g., FREQ=WEEKLY;BYDAY=MO)

update_event

Parameter

Type

Required

Description

event_id

string

Yes

Event UID to update

title

string

No

New title

start_time

string

No

New start time (ISO 8601)

end_time

string

No

New end time (ISO 8601)

start_date

string

No

New start date for all-day events (YYYY-MM-DD)

end_date

string

No

New end date for all-day events (YYYY-MM-DD)

is_all_day

boolean

No

Change to all-day event

description

string

No

New description

location

string

No

New location

timezone

string

No

IANA timezone (e.g., America/New_York)

rrule

string

No

Recurrence rule (e.g., FREQ=WEEKLY;BYDAY=MO)

delete_event

Parameter

Type

Required

Description

event_id

string

Yes

Event to delete

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

Control

Implementation

Credential Storage

Environment variables only, never logged or exposed

Input Validation

All inputs validated (calendar IDs, dates, times, text fields)

SSRF Protection

Blocks internal IPs, localhost, and dangerous URI schemes

Rate Limiting

Sliding window: 60 reads/min, 20 writes/min

Error Handling

Passwords, tokens, paths, emails sanitized from errors

Injection Prevention

ICS content properly escaped, command injection tested

ETag Normalization

RFC 7232 compliant, strips quotes/W/ prefix/XML entities

Content-Length Guard

Early rejection of oversized responses before buffering

Circuit Breaker

Prevents cascading failures with automatic recovery

Audit Logging

CUD operations logged via MCP logging protocol (MCP08)

ReDoS Protection

All regex patterns tested for catastrophic backtracking

Unicode Security

Homoglyph, normalization, and encoding bypass protection

OWASP MCP Top 10 Coverage

Risk

Mitigation

Tests

MCP01: Token Mismanagement

Credentials masked in logs/errors, secure storage

14

MCP02: Privilege Escalation

Fixed tool set, no dynamic registration

5

MCP03: Tool Argument Injection

Input validation, parameterized operations

8

MCP04: Sensitive Data Exposure

Error sanitization, credential masking

10

MCP05: Command Injection

Input treated as data, not executed

3

MCP06: Prompt Injection

Malicious text stored as data, not interpreted

3

MCP08: Insecure Logging

Rate limiting, sensitive data sanitization

31

MCP09: Resource Exhaustion

Rate limiting, input size limits, DoS protection

25

MCP10: Context Over-sharing

Isolated state, no cross-request data leakage

3

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)

Category

Tests

Description

Security

282

Adversarial inputs, OWASP MCP Top 10, ReDoS, Unicode

CalDAV Protocol

181

XML parsing, HTTP client, models, ETag normalization

ICS Format

150

RFC 5545 parsing, building, patching

Error Handling

56

Secure error responses, credential sanitization

Integration

45

End-to-end tools, MCP spec compliance, annotations

Input Validation

44

All parameter validation rules

Service Layer

26

Calendar operations, caching

Rate Limiting

18

Concurrent access, window reset

Cancellation

12

Operation cancellation, cleanup

Logging

9

MCP logging compliance

Progress

9

Progress reporting

E2E

11

Live CalDAV + end-to-end integration

Security Test Categories

Category

Tests

Coverage

Adversarial Inputs

53

SQL/NoSQL injection, XSS, path traversal

ICS Patcher Security

43

CRLF injection, property injection, encoding attacks

Unicode Security

38

Homoglyphs, normalization, RTL override

Logger Security

31

Log injection, credential sanitization

OWASP MCP Risks

29

MCP01-10 specific attack vectors

Progress Security

27

Token enumeration, injection

ReDoS Protection

25

Catastrophic backtracking, resource exhaustion

Cancellation Security

22

Replay attacks, race conditions

Credential Security

14

Token masking, secure storage

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

This server cannot be installed

F
license - not found
-
quality - not tested
C
maintenance

How are these scores calculated?

Maintenance

–Maintainers
–Response time
2moRelease cycle
4Releases (12mo)
Commit activity
Issues opened vs closed

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Servers

View all related MCP servers

Related MCP Connectors

  • CalendarMCP

    Hosted Google Calendar MCP server for AI agents. No self-hosting or Google Cloud setup.

  • google-mcp

    Streamable HTTP MCP server for Google Calendar and Sheets with OAuth login.

  • Withings Health Data

    MCP server for Withings health data — sleep, activity, heart, and body metrics.

View all MCP Connectors

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/icloud-calendar-mcp/icloud-calendar-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server