icloud-mcp
Manage an iCloud account through MCP for calendar, contacts, and mail.
Calendar: list calendars/subscriptions, list/search events, create/update/delete events, handle recurring events, reminders, timezones, all-day events, attendees, invitations, and cancellations.
Contacts: list/search/get/create/update/delete contacts, including notes, phones, emails, addresses, organization, title, and label preservation.
Email: list folders/messages, search server-side, read full messages and bodies, fetch attachments, send HTML/plain mail with attachments and threaded replies, save drafts, move/delete messages, and mark read/unread.
Deployment: run locally over stdio or remotely over stateless HTTP with per-request credentials, optional bearer auth, send allowlists, tool-category filtering, and iCloud-host restrictions.
Provides tools for managing iCloud calendars (CalDAV), contacts (CardDAV), and email (IMAP/SMTP).
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@icloud-mcp list my upcoming events for today"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
iCloud MCP Server
Model Context Protocol server for iCloud. Gives Claude (Desktop, Code, claude.ai connectors) and any other MCP client full access to an iCloud account:
Calendar (CalDAV): list/search/create/update/delete events, recurring events (RRULE), alerts (VALARM), IANA timezones, all-day events, iTIP invitations and cancellations by email.
Contacts (CardDAV): list/search/get/create/update/delete, including notes; labels (home/work/custom) survive updates.
Mail (IMAP/SMTP): folders, listing, server-side search, full messages with attachments, attachment download, sending (HTML, attachments, threaded replies), drafts, move/delete/read flags.
Runs in two modes with the same code:
Mode | Transport | Typical use | Credentials |
Local ("offline") | stdio | Claude Desktop / Claude Code launch it as a subprocess on your machine |
|
Server | Streamable HTTP, stateless | Docker / Cloud Run / any host, many users | Per-request headers or HTTP Basic auth, env fallback |
Tools
Tool | Description |
| Calendars with IDs; Reminders lists are flagged |
| Events in a date range, recurring series expanded per occurrence, sorted by start |
| Subscribed (webcal/ICS) calendars with IDs and feed host (never the feed URL) |
| Events from subscribed calendars, fetched from their feeds; failures reported in |
| Text search over summary/description/location |
| Create an event: timezone, all-day, |
| Partial update; change timezone/recurrence/alerts; re-sends invitations when attendees change |
| Delete and email cancellations to attendees |
| Read contacts (name, phones, emails, addresses, organization, title, notes) |
| Write contacts |
| Folders with IMAP flags |
| Newest messages of a folder with readable |
| Server-side IMAP search: |
| Full message(s): headers, |
| Download an attachment: save to a local directory (stdio) or return it inline |
| Send mail: multiple recipients, CC/BCC, HTML with auto plain-text alternative, local file attachments, threaded reply ( |
| Same inputs as |
| Move between folders; delete to Trash ( |
| Toggle |
Every tool carries MCP annotations (readOnlyHint, destructiveHint) so clients can ask for confirmation before writes. Errors are returned as MCP tool errors with actionable messages (e.g. wrong password vs. missing credentials).
Behaviour worth knowing
IDs: calendar/contact/event IDs are full URLs, pass them back verbatim. Email IDs are IMAP UIDs and are only valid inside the folder they came from.
Times: pass
YYYY-MM-DDTHH:MM:SSplus an IANAtimezone(default:DEFAULT_TIMEZONE, which falls back to the machine's zone, then UTC) orYYYY-MM-DDfor all-day events. Returned times are ISO 8601 with offset.Recurring events:
calendar_list_eventsreturns one entry per occurrence; update/delete apply to the whole series.Email bodies are converted from HTML to readable text and truncated to
EMAIL_BODY_MAX_CHARS(20 000) so newsletters do not flood the model context.full_html=truereturns the raw HTML too.Attachments on disk (
save_dir,attachment_paths) are enabled by default in stdio mode and disabled in HTTP mode. Override withICLOUD_MCP_LOCAL_FILESand restrict to a folder withICLOUD_MCP_LOCAL_FILES_ROOT.Rich text that users paste into event notes/locations or contact notes comes back from iCloud as HTML; it is converted to Markdown so links and lists survive (
ICLOUD_HTML_MODE=markdown, default), rendered to plain text (text) or passed through (raw).Tool groups can be switched off per instance with
ICLOUD_ENABLED_CATEGORIES=calendar,contacts,email(e.g. a read-only mail agent getsemailonly).Only iCloud hosts are ever contacted with the account's credentials: calendar, event and contact URLs on any other host are rejected, and mail headers are validated against injection.
Outbound recipients can be restricted with
EMAIL_SEND_ALLOWLIST=@mycompany.com,partner@example.com; it applies toemail_send,email_save_draftand calendar invitations, so a prompt-injected agent cannot mail data to arbitrary addresses.
Related MCP server: orchard-mcp
Requirements
Python 3.11+ (tested on 3.12 and 3.14) or Docker
An iCloud account and an app-specific password: https://account.apple.com/account/manage → Sign-In and Security → App-Specific Passwords. iCloud Mail additionally needs an active
@icloud.com/@me.com/@mac.comaddress.
Local mode (Claude Desktop / Claude Code)
1. Install
git clone https://github.com/mike-tih/icloud-mcp.git
cd icloud-mcp
uv venv && uv pip install -e . # or: python3 -m venv .venv && .venv/bin/pip install -e .
cp .env.example .env # add ICLOUD_EMAIL / ICLOUD_APP_SPECIFIC_PASSWORDTry it:
.venv/bin/icloud-mcp --help2. Claude Code
claude mcp add icloud -- /absolute/path/to/icloud-mcp/.venv/bin/icloud-mcpor, without a checkout at all:
claude mcp add icloud -e ICLOUD_EMAIL=you@icloud.com -e ICLOUD_APP_SPECIFIC_PASSWORD=xxxx-xxxx-xxxx-xxxx \
-- uvx --from git+https://github.com/mike-tih/icloud-mcp icloud-mcp3. Claude Desktop
Config file: macOS ~/Library/Application Support/Claude/claude_desktop_config.json, Windows %APPDATA%\Claude\claude_desktop_config.json.
{
"mcpServers": {
"icloud": {
"command": "/absolute/path/to/icloud-mcp/.venv/bin/icloud-mcp",
"env": {
"ICLOUD_EMAIL": "you@icloud.com",
"ICLOUD_APP_SPECIFIC_PASSWORD": "xxxx-xxxx-xxxx-xxxx",
"DEFAULT_TIMEZONE": "Europe/Berlin"
}
}
}
}python /absolute/path/to/icloud-mcp/run.py works as the command too. Restart Claude Desktop completely after editing the file; the server shows up under the tools icon.
Server mode (Streamable HTTP)
icloud-mcp --http # 0.0.0.0:8000/mcp, stateless
icloud-mcp --http --port 9000 --path /icloud --statefulOr with Docker:
docker compose up -d # reads .env for optional fallback credentials
curl http://localhost:8000/healthThe image runs icloud-mcp --http with PORT from the environment, so it works unchanged on Cloud Run, Fly.io, Railway etc. The server is stateless: every request carries its own credentials, no sessions are kept, and instances can be scaled horizontally.
Authentication (per request)
Checked in order:
Headers
X-Apple-EmailandX-Apple-App-Specific-PasswordAuthorization: Basic base64(email:app-specific-password)Environment
ICLOUD_EMAIL/ICLOUD_APP_SPECIFIC_PASSWORD(single-user deployments)
Protecting the endpoint
Set MCP_AUTH_TOKEN to a long random secret. Every MCP request must then carry it as Authorization: Bearer <token> or X-MCP-Token: <token> (/health stays open). Without a token the server logs a warning and ignores the environment credentials over HTTP, so an unprotected port can never hand out the operator's account; per-request credentials still work. Set ICLOUD_MCP_ALLOW_ENV_CREDENTIALS=true only if you really want an open endpoint bound to one account (e.g. on a private network). docker-compose.yml publishes the port on 127.0.0.1 only.
MCP_AUTH_TOKEN=$(openssl rand -hex 32) icloud-mcp --http
claude mcp add --transport http icloud https://mcp.example.com/mcp \
-H "Authorization: Bearer <token>" \
-H "X-Apple-Email: you@icloud.com" -H "X-Apple-App-Specific-Password: xxxx-xxxx-xxxx-xxxx"Example with Claude Code against a remote server:
claude mcp add --transport http icloud https://mcp.example.com/mcp \
-H "X-Apple-Email: you@icloud.com" -H "X-Apple-App-Specific-Password: xxxx-xxxx-xxxx-xxxx"Always put the server behind HTTPS: app-specific passwords travel in headers.
Configuration
All settings are environment variables (a .env file next to the checkout is loaded). See .env.example for the full list. The important ones:
Variable | Default | Purpose |
| – | Fallback credentials |
| machine zone or | Timezone for naive event times; set explicitly on servers |
|
| Body truncation |
|
| Outgoing attachment budget |
| – | Allowed outbound addresses/domains (send, drafts, invitations) |
| stdio: on, HTTP: off | Allow reading/writing attachments on the server's disk |
| – | Confine those files to a directory |
| – | Shared secret required on HTTP requests |
| true with token, else false | Serve the env account over HTTP |
|
| Tool groups to expose |
| (all) | Comma-separated subscription names; when set, only these subscribed calendars are read |
| (none) | Comma-separated subscription names to skip (applied after INCLUDE) |
|
| Allow subscription feeds whose host resolves to a private/loopback address |
|
| Rich text in event/contact fields: |
| stdio, | HTTP transport |
|
| Logging (always to stderr, stdout is reserved for stdio) |
Troubleshooting
"Authentication required": no credentials reached the server. Check the
envblock / headers."iCloud rejected the credentials" / HTTP 401: wrong app-specific password, or the Apple ID password was used.
"IMAP login failed" but calendar works: the Apple ID has no iCloud Mail address (Apple IDs created with a third-party email cannot use iCloud Mail).
Events land at the wrong time: set
DEFAULT_TIMEZONEor passtimezoneexplicitly.HTTP 401
unauthorizedfrom the server itself:MCP_AUTH_TOKENis set and the request did not carry it."Refusing to use ... URL on untrusted host": an ID was not one returned by the list tools; pass the URL verbatim.
Server logs: everything goes to stderr; in Claude Desktop see Help → Show Logs.
Development
uv pip install -e ".[dev]"
pytest # unit tests + end-to-end through the MCP protocol with mocked IMAP
ruff check src testsProject layout:
src/icloud_mcp/
├── server.py # FastMCP app, tool definitions, CLI entrypoint
├── auth.py # per-request credential resolution
├── config.py # environment configuration and logging
├── calendar.py # CalDAV operations, RRULE/timezone handling, iTIP mail
├── contacts.py # CardDAV operations
├── mail.py # IMAP/SMTP operations
├── mail_utils.py # MIME parsing, HTML→text, attachments, special folders, header validation
├── html_render.py # HTML→Markdown for rich text in event/contact fields
└── urls.py # iCloud host allow-list for calendar/contact URLsLicense
MIT, see LICENSE.
Available Tools
24 toolscalendar_create_eventCalendar Create EventA
Create a calendar event (optionally recurring, with alerts) and email iTIP invitations to attendees.
Returns the created event including its id/url. If some invitations could not be sent,
invitations_failed lists those addresses.
Inputs: end (required), start (required), summary (required), rrule, +6 more. Returns: object
calendar_delete_eventCalendar Delete EventADestructive
Delete an event (the whole series for recurring events) and email cancellations to its attendees.
Inputs: event_id (required). Returns: object
calendar_list_calendarsCalendar List CalendarsARead-onlyIdempotent
List the account's calendars with their IDs (URLs).
Reminders lists are included with read_only=true; they cannot hold events.
Inputs: no named parameters. Returns: result
calendar_list_eventsCalendar List EventsARead-onlyIdempotent
List events in a date range, sorted by start.
Each entry has id/url, summary, description, location, start, end (ISO 8601 with offset, or a date for all_day events), start_timezone, recurring, rrule, attendees and calendar. Recurring series are expanded into one entry per occurrence; all occurrences share the series id, so update/delete apply to the whole series.
Inputs: end_date, start_date, calendar_id. Returns: result
calendar_search_eventsCalendar Search EventsARead-onlyIdempotent
Search events by text within an optional date range (same output as calendar_list_events).
Inputs: query (required), end_date, start_date, calendar_id. Returns: result
calendar_update_eventCalendar Update EventADestructive
Update fields of an existing event. Only provided fields change; recurring series are updated as a whole.
Inputs: event_id (required), end, rrule, start, +6 more. Returns: object
contacts_createContacts CreateA
Create a contact in the default address book and return it with its id/url.
Inputs: name (required), notes, title, emails, +3 more. Returns: object
contacts_deleteContacts DeleteADestructive
Delete a contact permanently.
Inputs: contact_id (required). Returns: object
contacts_getContacts GetARead-onlyIdempotent
Get one contact with all fields.
Inputs: contact_id (required). Returns: object
contacts_listContacts ListARead-onlyIdempotent
List contacts from the default address book: id/url, name, phones, emails, addresses, organization, title, notes.
Inputs: limit. Returns: result
contacts_searchContacts SearchARead-onlyIdempotent
Find contacts by name, organization, email or phone number.
Inputs: query (required), limit. Returns: result
contacts_updateContacts UpdateADestructive
Update a contact. Only provided fields change; list fields replace the existing values (entries that keep the same number/address keep their labels such as home/work).
Inputs: contact_id (required), name, notes, title, +4 more. Returns: object
email_deleteEmail DeleteADestructive
Move a message to Trash, or delete it permanently.
Inputs: message_id (required), folder, permanent. Returns: object
email_get_attachmentEmail Get AttachmentARead-onlyIdempotent
Download an email attachment.
With save_dir the file is written to disk and its path returned; otherwise the file is returned inline (images as image content, other types as an embedded resource).
Inputs: attachment (required), message_id (required), folder, save_dir.
email_get_messageEmail Get MessageARead-onlyIdempotent
Get one message: headers (from, to, cc, reply_to, date, Message-ID), flags, body_text and the attachments list.
Attachments are described by index, name, mime_type and size; download one with email_get_attachment.
Inputs: message_id (required), folder, full_html, include_body. Returns: object
email_get_messagesEmail Get MessagesARead-onlyIdempotent
Fetch several messages in one round trip (same fields as email_get_message). Missing IDs yield an error entry.
Inputs: message_ids (required), folder, full_html, include_body. Returns: result
email_list_foldersEmail List FoldersARead-onlyIdempotent
List mail folders with their IMAP flags (e.g. \Sent, \Trash).
Inputs: no named parameters. Returns: result
email_list_messagesEmail List MessagesARead-onlyIdempotent
List the newest messages in a folder: id, subject, from, to, date, flags, unread, has_attachments and body_text.
Inputs: limit, folder, unread_only, include_body. Returns: result
email_mark_readEmail Mark ReadB
Mark a message as read (set \Seen).
Inputs: message_id (required), folder. Returns: object
email_mark_unreadEmail Mark UnreadA
Mark a message as unread (clear \Seen).
Inputs: message_id (required), folder. Returns: object
email_moveEmail MoveADestructive
Move a message to another folder. The message gets a new UID in the destination folder.
Inputs: to_folder (required), message_id (required), from_folder (required). Returns: object
email_save_draftEmail Save DraftA
Save a message to the Drafts folder without sending it, so the user can review and send it from any mail client.
Inputs: body (required), subject (required), cc, to, +5 more. Returns: object
email_searchEmail SearchARead-onlyIdempotent
Server-side IMAP search. All provided filters are combined with AND; at least one is required.
Returns the same fields as email_list_messages, newest first.
Inputs: body, limit, query, since, +7 more. Returns: result
email_sendEmail SendA
Send an email from the account (SMTP) and store a copy in the Sent folder.
Inputs: to (required), body (required), subject (required), cc, +5 more. Returns: object
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 24 tools
Each tool maps to a distinct resource-action pair across calendar, contacts, and email, with list/search/get variants clearly separated by purpose. Batch operations and single-item fetches are explicitly distinguished, and no two tools appear interchangeable.
All tool names follow a uniform lowercase snake_case pattern of domain_verb_noun, such as calendar_create_event, contacts_update, and email_list_messages. The domain prefix makes the resource area immediately clear, and there are no mixed conventions or vague verbs.
24 tools is above the typical single-domain range, but the server intentionally covers three distinct iCloud domains—Calendar, Contacts, and Mail—and each tool serves a specific operational need. The count is slightly heavy but well justified by the breadth of functionality exposed.
Calendar events and contacts have full create/read/update/delete coverage, while email covers searching, fetching, sending, drafting, moving, deleting, and read-state management. Recurring events, invitations, and attachments are handled, leaving no obvious dead ends in the core workflows.
Maintenance
Related MCP Connectors
Read and send iCloud Mail, manage iCloud Calendar. Needs an approved account at icloud.mcp.visin.ch.
A MCP server that works with Outlook Calendar to manage event listing, reading, and updates.
A MCP server that works with Google Calendar to manage event listing, reading, and updates.
MCP server for Nylas — read email, calendars, events and contacts, and send email or create events.
Related MCP Servers
- FlicenseNot gradedqualityBmaintenanceMCP server for iCloud (Apple) Calendar access via CalDAV24-
- AlicenseNot gradedqualityDmaintenanceMCP server for Apple Calendar, Mail, Reminders, and Files on macOS using native frameworks.24 npm22MIT
- AlicenseNot gradedqualityDmaintenanceMCP server for iCloud integration, enabling management of calendars (CalDAV), contacts (CardDAV), and email (IMAP/SMTP) through natural language.MIT
- -licenseNot gradedqualityNot gradedmaintenanceAn MCP server for iCloud Calendar, Contacts, and Mail, usable from any MCP-capable AI client.-