A Model Context Protocol server that gives AI assistants full access to Apple iCloud Calendar through CalDAV. List calendars, search events, create, update, and delete events -- all from Claude or any MCP-compatible client.
Built with Go and the mcp-go SDK. Ships as a single static binary for Linux, macOS, and Windows.
A Go-based MCP server for Apple iCloud Calendar via CalDAV — manage calendars and events through AI assistants with cross-platform support.
List all iCloud calendars with paths, names, descriptions, and colors
Search events with date range filters and pagination
Create events with title, time, description, location, and attendees
Update individual fields on existing events (partial update with pointer fields)
Delete events permanently
Recurring Events & Attendees
Expand recurring events (RRULE) into individual occurrences within a date range
Manage attendees with roles (CHAIR, REQ-PARTICIPANT, OPT-PARTICIPANT) and statuses
Multi-Account Support
Manage multiple iCloud accounts from a single server instance
Configure via ACCOUNTS_FILE JSON or single-account environment variables
Per-account rate limiting and retry logic
Operational
Structured JSON logging with UUID request correlation
Configurable timeout middleware on every tool call (default 25s)
Automatic retry with exponential backoff for transient failures
Rate limiting per account to avoid iCloud throttling
Health endpoint (/healthz, /readyz) and Prometheus metrics (/metrics)
Audit logging for mutating operations (no PII)
Input validation for all tool parameters
MCP tool annotations (read-only, destructive, idempotent) for client-side safety
Graceful shutdown on SIGTERM/SIGINT
mTLS and custom CA support for enterprise deployments
file:// credential loading for Docker/Kubernetes secrets
CI pipeline with tests, linting, and vulnerability scanning
Quick Start
# Install
go install github.com/rgabriel/mcp-icloud-calendar@latest
# Set credentials (app-specific password, not your main iCloud password)
export ICLOUD_EMAIL="[email protected]"
export ICLOUD_PASSWORD="xxxx-xxxx-xxxx-xxxx"
# Run
mcp-icloud-calendar
Or download a prebuilt binary from the Releases page.
Prerequisites
Go 1.21+ -- install (only needed when building from source)
iCloud account with two-factor authentication enabled
App-specific password -- required for CalDAV access
The server exposes 5 MCP tools. Each tool includes schema constraints and annotations indicating whether it is read-only, destructive, or idempotent.
list_calendars
List all available iCloud calendars. Returns each calendar's path, display name, description, and color. Call this first to discover valid calendarId values.
Parameter
Type
Default
Description
account
string
Account name for multi-account setups
search_events
Search for calendar events within a date range. Returns paginated results with event details including recurrence info and attendees.
Parameter
Type
Default
Description
account
string
Account name for multi-account setups
calendarId
string
(server default)
Calendar path from list_calendars
startTime
string
Start of date range (RFC 3339, e.g., 2025-03-01T00:00:00Z)
endTime
string
End of date range (RFC 3339)
limit
number
50
Max events to return (1-500)
offset
number
0
Events to skip for pagination
expandRecurrence
boolean
false
Expand recurring events into individual occurrences (requires both startTime and endTime)
create_event
Create a new calendar event. Returns the created event's unique ID.
Update specific fields of an existing event. Only include the fields you want to change -- omitted fields remain unchanged.
Parameter
Type
Default
Description
account
string
Account name for multi-account setups
eventId
string
(required)
Event ID (UID) from search_events
calendarId
string
(server default)
Calendar path containing the event
title
string
Updated title
description
string
Updated description
location
string
Updated location
startTime
string
Updated start time (RFC 3339)
endTime
string
Updated end time (RFC 3339)
delete_event
Permanently delete a calendar event. This action cannot be undone.
Parameter
Type
Default
Description
account
string
Account name for multi-account setups
eventId
string
(required)
Event ID (UID) from search_events
calendarId
string
(required)
Calendar path containing the event
Development
Building
make build # Build binary with version embedding
make test # Run tests with race detector
make lint # Run golangci-lint
make clean # Remove build artifacts
make docker # Build Docker image
make run # Build and run
Running Locally
export ICLOUD_EMAIL="[email protected]"
export ICLOUD_PASSWORD="xxxx-xxxx-xxxx-xxxx"
make run
Testing
The project includes 88 table-driven tests across 14 test files, covering all tool handlers, CalDAV client logic, input validation, retry/rate-limiting wrappers, recurrence expansion, attendee parsing, and error paths. Tests use mock implementations of the CalendarService interface -- no live CalDAV connection required.
make test
Testing with MCP Inspector
Use the MCP Inspector to interactively test the server:
Client chain: Each account gets its own pipeline: realClient -> RateLimitedClient -> RetryClient
Middleware chain: Each tool call passes through RequestID -> Timeout -> Metrics -> handler. The request ID middleware assigns a UUID for log correlation. The timeout middleware enforces a configurable deadline. The metrics middleware records tool call duration and outcome.
Audit logging: Mutating operations (create_event, update_event, delete_event) are logged via a post-call hook with tool name, account, calendar ID, and status -- no PII (titles, descriptions, locations) is included.
คัดลอกคอนฟิก stdio สำหรับ Cursor, Claude Desktop, Claude Code หรือ VS Code ได้ในหน้านี้ คอนฟิกนี้ใช้การติดตั้งของผู้เผยแพร่ ไม่ใช่พร็อกซีของ PlugMCP
MCP Icloud Calendar ต้องใช้ API key ไหม?
ระเบียนนี้ไม่ได้ระบุตัวแปรสภาพแวดล้อมที่จำเป็น
MCP Icloud Calendar ใช้ทรานสปอร์ตแบบใด?
MCP Icloud Calendar ทำงานแบบโลคัลผ่าน stdio
MCP Icloud Calendar ถูกตรวจสอบล่าสุดเมื่อใด?
ตรวจสอบล่าสุดเมื่อ 2026-10-27 A Go-based MCP server for Apple iCloud Calendar via CalDAV — manage calendars and events through AI assistants with cross-platform support.