iCloud MCP

Give Claude your iCloud: Mail, Calendar, Contacts, Reminders, Notes and iCloud Drive. Self-hosted, single-owner, and built around your approval, not the model's good behaviour.

Why · What you can ask · How it works · Security · Quick start · Run locally · Tools · Mac helper · Configuration · Troubleshooting

A self-hosted Model Context Protocol server that connects Claude (or any MCP client) to your Apple iCloud account through one custom connector. Mail, Calendar and Contacts speak the standard IMAP, SMTP, CalDAV and CardDAV protocols. Reminders, Notes and iCloud Drive, which Apple only exposes on its own devices, go through an optional helper on your Mac.

Why iCloud MCP

What you can ask Claude

• "Find the email from my landlord about the heating and draft a polite reply."
• "What's on my calendar next week? Move Thursday's dentist appointment to Friday at the same time."
• "Add Anna's new work address to her contact card."
• "Remind me to renew my passport on the first of next month."
• "Move all my recipe notes into a Recipes folder, and delete the three empty notes."
• "Find my tax return PDF in iCloud Drive and tell me what I paid last year."

How it works

flowchart TB
    C["<b>Claude</b><br/>or any MCP client"] -->|"OAuth + MCP over HTTPS"| S["<b>icloud-mcp</b><br/>on your server"]
    M["<b>Mac helper</b><br/>optional"] -->|"polls out over pinned TLS"| S
    S -->|"IMAP · SMTP · CalDAV · CardDAV"| I["<b>iCloud</b><br/>Mail · Calendar · Contacts"]
    M -->|"EventKit · scripts · files"| A["<b>On your Mac</b><br/>Reminders · Notes · iCloud Drive"]
    classDef you fill:#eef6ff,stroke:#0969da,color:#0b1f33
    classDef apple fill:#f6f8fa,stroke:#57606a,color:#1f2328
    class S,M you
    class I,A apple

The server runs anywhere Docker runs (a home server, a Raspberry Pi, a small VPS) behind a public HTTPS address such as a Cloudflare Tunnel. If you only use Claude Desktop or Claude Code, you can skip all of that and run it locally instead. The Mac helper is only needed for Reminders, Notes and iCloud Drive. It connects out to the server, so your Mac never opens a port.

Security first

A connector that can read your mail and act for you is a prompt-injection target: a hostile email or calendar invite can contain text that tries to steer the agent. The server labels all such content as untrusted and tells agents to treat it as data, but that is a request to a language model, not a guarantee. What actually protects you is configuration:

In Claude you can also set the send, reply, forward and delete tools to "ask before use". Anyone who obtains the app-specific password has full access to mail, calendar and contacts (Apple offers no narrower scope), so protect the server and its .env accordingly.

Quick start

You need:

• Docker with the compose plugin (or Python 3.11+)
• An Apple Account with two-factor authentication and an app-specific password (account.apple.com → Sign-In and Security → App-Specific Passwords)
• A public HTTPS address for the server. Claude connects from Anthropic's cloud, so a LAN or VPN address won't work. A Cloudflare Tunnel is the simplest option: outbound only, no port forwarding.
• A Claude plan that supports custom connectors

1. Configure

git clone https://github.com/epinethrone/icloud-mcp.git && cd icloud-mcp
cp .env.example .env     # fill in ICLOUD_USERNAME, ICLOUD_APP_PASSWORD, ICLOUD_DISPLAY_NAME,
                         # MCP_PUBLIC_URL (your https address, no trailing slash), MCP_OWNER_PASSWORD
chmod 600 .env

MCP_OWNER_PASSWORD is a new random password (12+ characters) that you type when approving a client and on the outbox page. It is not your Apple password. ./configure.sh asks for the secrets with silent prompts if you prefer.

2. Check your credentials against the real iCloud before exposing anything

docker build -t icloud-mcp:local .
docker run --rm --env-file .env icloud-mcp:local python -m icloud_mcp.selftest                              # logs in to IMAP, SMTP, CalDAV, CardDAV; sends nothing
docker run --rm --env-file .env icloud-mcp:local python -m icloud_mcp.selftest --probe-sent you@example.com   # sends ONE test mail

If a login fails, the login name is the usual cause: set IMAP_USERNAME, SMTP_USERNAME, CALDAV_USERNAME or CARDDAV_USERNAME separately.

3. Run it

docker compose up -d --build     # listens on 127.0.0.1:8000 only

For the bundled Cloudflare Tunnel: create a tunnel, point its public hostname (the host in MCP_PUBLIC_URL) at http://icloud-mcp:8000, put the token in .tunnel.env as TUNNEL_TOKEN=..., and start with docker compose --profile tunnel up -d --build. Any TLS front (Caddy, nginx) works too, as long as it keeps the Host header. MCP_PUBLIC_URL must match the public address exactly.

4. Connect Claude

Settings → Connectors → Add custom connector → https://<your-host>/mcp. Your server shows an approval page: enter the owner password. Reconnect the connector whenever you change tools or settings, because Claude caches tool definitions. To revoke every connected client, delete oauth_state.json in the data volume and restart.

5. Check it works

In a new chat, open the tools menu: the connector should be listed with its tools. Then try a few read-only requests:

• "List my mail folders."
• "What's on my calendar this week?"
• "Find Anna in my contacts."
• "Is the Mac helper online?" (only if you set up the Mac helper)

Then ask Claude to email yourself. With the default settings nothing is sent: the message waits at https://<your-host>/outbox until you approve it. If anything fails, see Troubleshooting.

Approving outgoing mail

With the default SEND_REQUIRES_APPROVAL=true, mail_send, mail_reply and mail_forward return queued_for_owner_approval and nothing leaves. Open https://<your-host>/outbox (bookmark it, and only type the password there, never on a link an agent gives you), enter the owner password, review the exact recipients and text, then approve or discard. Queued messages expire after OUTBOX_TTL_SECONDS (24 hours by default) and are released at most once.

Run it locally (Claude Desktop and Claude Code)

The same server can run on your own computer as a local MCP server. Your desktop client starts it when it needs it and talks to it over stdio, so there is no public address, tunnel, Docker or OAuth. Claude on the web and on your phone cannot reach it, which is the trade-off.

Claude Desktop in one click

1. Download icloud-mcp-<version>.mcpb from the latest release.
2. Double-click it (or drag it onto Claude Desktop → Settings → Extensions).
3. Fill in the form: your Apple Account email, an app-specific password (Claude Desktop keeps it in your system keychain), your name and time zone. The safety switches start approval-first: mail is saved to Drafts for you to send, invitations to other people are off.

That covers Mail, Calendar and Contacts. Reminders, Notes and iCloud Drive need the Mac helper and the manual setup below.

Manual setup (Claude Code, or Claude Desktop with more options)

1. Put your settings in a file only you can read

mkdir -p ~/.icloud-mcp && chmod 700 ~/.icloud-mcp
cat > ~/.icloud-mcp/icloud.env <<'END'
ICLOUD_USERNAME=you@icloud.com
ICLOUD_APP_PASSWORD=xxxx-xxxx-xxxx-xxxx
ICLOUD_DISPLAY_NAME=Your Name
DEFAULT_TIMEZONE=Europe/Berlin
END
chmod 600 ~/.icloud-mcp/icloud.env

Any setting from Configuration can go in this file. MCP_PUBLIC_URL and MCP_OWNER_PASSWORD are not needed.

On a Mac, keep the password out of the file entirely: run uvx icloud-mcp-server --store-password once. It asks for the app-specific password (it never appears on the command line) and saves it in your login Keychain; then delete the ICLOUD_APP_PASSWORD line. The server reads it from the Keychain whenever ICLOUD_APP_PASSWORD is not set.

Fewer tools, better choices: clients pick the right tool more reliably from a short list. Add TOOLS=essential for a core of about 19 (search, read and reply to mail; list, find free time and create events; find contacts; the main Reminders, Notes and Drive tools; the health check), or list exact names, e.g. TOOLS=essential,mail_move.

2. Add it to your client (needs uv)

Claude Code:

claude mcp add icloud -- uvx icloud-mcp-server --local --env-file ~/.icloud-mcp/icloud.env

Claude Desktop: Settings → Developer → Edit Config, then add this to claude_desktop_config.json and restart Claude:

{
  "mcpServers": {
    "icloud": {
      "command": "uvx",
      "args": ["icloud-mcp-server", "--local", "--env-file", "/Users/YOU/.icloud-mcp/icloud.env"]
    }
  }
}

If Claude Desktop cannot find uvx, use its full path (which uvx). Without uv, pip install icloud-mcp-server and use icloud-mcp as the command.

How sending works locally. There is no approval page, so with the default SEND_REQUIRES_APPROVAL=true every message Claude sends is saved to your Drafts folder instead, and the result says so. You review it in Mail and press Send yourself. Set SEND_REQUIRES_APPROVAL=false to let Claude send directly; your client's own "ask before use" setting is then the only check.

Reminders, Notes and iCloud Drive locally. Add ENABLE_REMINDERS=true (and/or ENABLE_NOTES, ENABLE_DRIVE) and a BRIDGE_TOKEN to the env file, start your client once, then install the Mac helper with server https://127.0.0.1:8001 and the fingerprint from ~/.icloud-mcp/bridge_fingerprint.txt. In local mode the bridge only listens on 127.0.0.1. If two clients start the server at once, only the first gets the Mac tools; Mail, Calendar and Contacts work in both.

Tools

27 tools for Mail, Calendar and Contacts, plus 22 more with the optional Mac helper.

Reminders, Notes and iCloud Drive through your Mac

Apple only exposes Reminders, Notes and iCloud Drive on its own devices, so a small helper (mac-helper/) runs on your Mac and does the work when the server asks.

• Nothing listens on your Mac. The helper connects out to a private HTTPS port of the server (never the public address, never the tunnel) and long-polls for jobs.
• No code is ever sent. The server sends an operation name and validated arguments from a fixed list. Reminders run a small EventKit program the installer builds on your Mac. Notes run static scripts. iCloud Drive runs one fixed Python script under Apple's own Python. In every case the arguments arrive as one JSON value, never as code.
• Pinned and authenticated. TLS with a self-signed certificate the helper pins by fingerprint, plus a bearer token.
• Honest when it's off. It works while your Mac is on and reachable (home network or VPN). When it isn't, the tools say so.

Enable it in .env with any of ENABLE_REMINDERS=true, ENABLE_NOTES=true and ENABLE_DRIVE=true, a BRIDGE_TOKEN of at least 32 random characters, and BRIDGE_BIND set to the address the Mac reaches the server on. The server logs the certificate fingerprint for the installer, and also writes it to bridge_fingerprint.txt in its data folder. Then follow the Mac helper guide.

The Notes scripts are adapted from MrGo2/icloud-mcp (MIT); see THIRD_PARTY_NOTICES.md.

Configuration

Everything is an environment variable. .env.example has a comment for each one.

iCloud quirks this project works around

These only show up against Apple's real servers, never against local test servers:

• CalDAV rejects UID-filtered queries (412), so events are fetched by resource name with a scan fallback. An attendee who is the account owner is rewritten to an internal path with the address in the EMAIL parameter.
• IMAP has no MOVE. Moving and deleting use COPY, flag \Deleted, then UID EXPUNGE of exactly those messages (never a plain EXPUNGE). iCloud doesn't file sent mail by itself.
• CardDAV discovery ends on a different host than it starts on (follow the returned links), returns the whole address book in one request, and stores about half of all emails in grouped itemN.EMAIL properties with labels in itemN.X-ABLabel.
• Travel time is a number Apple stores, not a live estimate. It is never recomputed, so an origin or travel mode without a duration is refused instead of silently doing nothing.

Limits

• Reminders, Notes and iCloud Drive need the Mac helper and a Mac that is on. Contact photos and notes are deliberately not exposed to agents, and deleting a contact is permanent.
• One identity: aliases can't be used as the From address. Attachments that aren't text come back as base64 and are size-capped.
• Each tool call opens a fresh connection, about 1.5 to 5 seconds per call against iCloud.
• Claude doesn't show custom icons for custom connectors yet (open request). The server serves and advertises the project logo anyway (src/icloud_mcp/static/), so clients that do show icons, and your browser tab on the approval and outbox pages, display it.

Troubleshooting

Contributing

Issues and pull requests are welcome.

• Security problems: please don't open a public issue. Follow the security policy instead.
• Before a pull request: make sure pytest tests --ignore=tests/integration passes, and add tests for new behaviour. They run automatically on every pull request.
• Anything that talks to iCloud: run selftest, and try it by hand against a real account. Local test servers accept things iCloud doesn't.
• New tools: keep the safety defaults intact. Anything that sends, invites or deletes must stay behind the existing settings, and anything read from iCloud must be treated as data, never as instructions.

Development

python -m venv .venv && . .venv/bin/activate
pip install -e ".[test]"
pytest tests --ignore=tests/integration      # offline tests, no network
sudo apt install dovecot-imapd && dev/start_local_stack.sh
pytest tests                                 # adds integration tests against local Dovecot, an SMTP sink and Radicale

dev/e2e_http.py drives a running server over HTTP (OAuth plus tool calls). Local test servers accept things iCloud doesn't (see the quirks above), so treat selftest and a manual run against a real account as part of testing any change.

Acknowledgements

Built on the MCP Python SDK, IMAPClient, caldav, icalendar, html2text, python-dateutil, Uvicorn and HTTPX. The Notes scripts are adapted from MrGo2/icloud-mcp (MIT).

License

MIT.