icloud-mcp

# iCloud MCP Server An [MCP (Model Context Protocol)](https://modelcontextprotocol.io) server that gives AI assistants access to your iCloud Mail and Calendar. Works with Claude, and any other MCP-compatible client. Apple is one of the few major platforms without an MCP connector. This fills that gap using standard, well-supported protocols — IMAP for mail and CalDAV for calendar — so it's reliable and doesn't depend on reverse-engineered APIs. ## What it does ### Mail (IMAP) - **Search emails** — full-text search across subject and body - **List emails** — browse any mailbox, filter by recency - **Read emails** — full headers, body, and attachment metadata - **Create drafts** — compose emails saved to your Drafts folder - **Send emails** — send directly via iCloud SMTP - **Move emails** — file emails between folders (archive, trash, custom folders) - **List mailboxes** — discover all your folders ### Calendar (CalDAV) - **List calendars** — see all your iCloud calendars - **List events** — browse events by date range - **Search events** — find events by title, description, or location - **Create events** — with reminders, location, description, all-day support - **Update events** — modify any field on existing events - **Delete events** — remove events by UID ## Prerequisites 1. **An Apple ID** with iCloud Mail and/or Calendar enabled 2. **An app-specific password** — your regular Apple ID password won't work with IMAP/CalDAV. Generate one at: - Go to [appleid.apple.com](https://appleid.apple.com/account/manage) - Sign-In and Security → App-Specific Passwords - Generate a new password and save it somewhere safe ## Installation ### Via pip ```bash pip install icloud-mcp ``` ### Via uvx (no install needed) ```bash uvx icloud-mcp ``` ### From source ```bash git clone https://github.com/garethmalna/icloud-mcp.git cd icloud-mcp pip install . ``` ## Configuration Set two environment variables: ```bash export ICLOUD_APPLE_ID="your.email@icloud.com" export ICLOUD_APP_PASSWORD="xxxx-xxxx-xxxx-xxxx" ``` Or copy `.env.example` to `.env` and fill in your credentials. ### Optional settings | Variable | Default | Description | |----------|---------|-------------| | `ICLOUD_IMAP_HOST` | `imap.mail.me.com` | IMAP server hostname | | `ICLOUD_IMAP_PORT` | `993` | IMAP server port | | `ICLOUD_SMTP_HOST` | `smtp.mail.me.com` | SMTP server hostname | | `ICLOUD_SMTP_PORT` | `587` | SMTP server port | | `ICLOUD_CALDAV_URL` | `https://caldav.icloud.com` | CalDAV endpoint URL | ## Usage with Claude Desktop Add to your Claude Desktop configuration (`~/Library/Application Support/Claude/claude_desktop_config.json`): ```json { "mcpServers": { "icloud": { "command": "icloud-mcp", "env": { "ICLOUD_APPLE_ID": "your.email@icloud.com", "ICLOUD_APP_PASSWORD": "xxxx-xxxx-xxxx-xxxx" } } } } ``` Or if running from source: ```json { "mcpServers": { "icloud": { "command": "python", "args": ["-m", "icloud_mcp"], "env": { "ICLOUD_APPLE_ID": "your.email@icloud.com", "ICLOUD_APP_PASSWORD": "xxxx-xxxx-xxxx-xxxx" } } } } ``` ## Usage with Docker ```bash docker build -t icloud-mcp . docker run -e ICLOUD_APPLE_ID="..." -e ICLOUD_APP_PASSWORD="..." icloud-mcp ``` ## Available tools | Tool | Description | |------|-------------| | `icloud_list_mailboxes` | List all mail folders | | `icloud_list_emails` | List recent emails from a mailbox | | `icloud_read_email` | Read a specific email (full content) | | `icloud_search_emails` | Search emails by text | | `icloud_move_email` | Move email between folders | | `icloud_create_draft` | Save a draft email | | `icloud_send_email` | Send an email | | `icloud_list_calendars` | List all calendars | | `icloud_list_events` | List events in a date range | | `icloud_get_event` | Get full event details | | `icloud_search_events` | Search events by text | | `icloud_create_event` | Create a new event | | `icloud_update_event` | Update an existing event | | `icloud_delete_event` | Delete an event | ## Security - **App-specific passwords only** — the server never touches your main Apple ID password. App-specific passwords can be revoked individually at any time from your Apple ID settings. - **Standard protocols** — uses IMAP and CalDAV, the same protocols Apple Mail and Calendar apps use. No private APIs, no scraping. - **Local execution** — runs on your machine. Your credentials never leave your environment. - **Read-first design** — most tools are read-only. Write operations (send, create, delete) require explicit tool calls. ## Roadmap - [ ] iCloud Contacts (CardDAV) — same protocol family, straightforward to add - [ ] iCloud Reminders — requires the pyicloud library or WebSocket approach - [ ] iCloud Notes — similar to Reminders, needs pyicloud - [ ] OAuth support — if Apple ever opens up OAuth for personal accounts - [ ] Attachment download — currently shows metadata; full download coming ## Contributing Contributions welcome. The architecture is modular — each service is a separate module (`mail.py`, `calendar.py`) with a shared config. Adding a new service means: 1. Create a new module (e.g. `contacts.py`) 2. Add tool definitions in `server.py` 3. Add any new dependencies to `pyproject.toml` ## License MIT