iCloud Mail & Calendar

An MCP (Model Context Protocol) 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
   • Sign-In and Security → App-Specific Passwords
   • Generate a new password and save it somewhere safe

Installation

Via pip

pip install icloud-mcp

Via uvx (no install needed)

uvx icloud-mcp

From source

git clone https://github.com/garethmalna/icloud-mcp.git
cd icloud-mcp
pip install .

Configuration

Set two environment variables:

export ICLOUD_APPLE_ID="[email protected]"
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):

{
  "mcpServers": {
    "icloud": {
      "command": "icloud-mcp",
      "env": {
        "ICLOUD_APPLE_ID": "[email protected]",
        "ICLOUD_APP_PASSWORD": "xxxx-xxxx-xxxx-xxxx"
      }
    }
  }
}

Or if running from source:

{
  "mcpServers": {
    "icloud": {
      "command": "python",
      "args": ["-m", "icloud_mcp"],
      "env": {
        "ICLOUD_APPLE_ID": "[email protected]",
        "ICLOUD_APP_PASSWORD": "xxxx-xxxx-xxxx-xxxx"
      }
    }
  }
}

Usage with Docker

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