icloud-mcp

<div align="center">

<!-- mcp-name: io.github.epinethrone/icloud-mcp -->

<picture>
  <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/epinethrone/icloud-mcp/main/assets/readme/hero-dark.svg">
  <img src="https://raw.githubusercontent.com/epinethrone/icloud-mcp/main/assets/readme/hero-light.svg" alt="iCloud MCP. Your iCloud, in Claude. Mail, Calendar, Contacts, Reminders, Notes and iCloud Drive." width="100%">
</picture>

<br>

[![PyPI](https://img.shields.io/pypi/v/icloud-mcp-server?style=flat-square&label=PyPI&color=0071e3)](https://pypi.org/project/icloud-mcp-server/)
[![Tests](https://img.shields.io/github/actions/workflow/status/epinethrone/icloud-mcp/tests.yml?style=flat-square&label=tests)](https://github.com/epinethrone/icloud-mcp/actions/workflows/tests.yml)
[![MCP Registry](https://img.shields.io/badge/MCP_Registry-listed-6e56cf?style=flat-square)](https://registry.modelcontextprotocol.io/v0/servers?search=io.github.epinethrone/icloud-mcp)
[![License: MIT](https://img.shields.io/badge/license-MIT-86868b?style=flat-square)](https://github.com/epinethrone/icloud-mcp/blob/main/LICENSE)
[![icloud-mcp MCP server on Glama](https://glama.ai/mcp/servers/epinethrone/icloud-mcp/badges/score.svg)](https://glama.ai/mcp/servers/epinethrone/icloud-mcp)

**[Install for Claude Desktop ›](#claude-desktop-in-one-click)** &nbsp;&nbsp; **[Add to Claude Code ›](#manual-setup-claude-code-or-claude-desktop-with-more-options)** &nbsp;&nbsp; **[Host it for every device ›](#quick-start)**

</div>

<br>

<p align="center">
Ask Claude about your week, your inbox or the file you saved last spring, and it just knows.<br>
iCloud MCP connects Claude, or any MCP client, to the Apple account you already live in.<br>
It runs on your own machine, keeps your password there, and asks before anything leaves.
</p>

<br>

<picture>
  <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/epinethrone/icloud-mcp/main/assets/readme/apps-dark.svg">
  <img src="https://raw.githubusercontent.com/epinethrone/icloud-mcp/main/assets/readme/apps-light.svg" alt="Six apps, one connector: Mail (14 tools), Calendar (8), Contacts (5), Reminders (6), Notes (7) and iCloud Drive (8), plus a health check." width="100%">
</picture>

<br><br>

<div align="center">

## Just ask.

*"Find the email from my landlord about the heating and draft a polite reply."*

*"When am I free for an hour next week? Book lunch with Anna then."*

*"Move Thursday's dentist appointment to Friday, same time. Only that one."*

*"Remind me to renew my passport on the first of next month."*

*"Find my tax return PDF in iCloud Drive and tell me what I paid last year."*

<br>

## Private by design.

**Your password stays home.**<br>
Apple has no sign-in for these services other than an app-specific password.<br>
It lives only on your machine or in your Mac's Keychain. Claude never sees it.

**Nothing leaves without you.**<br>
Mail Claude writes waits for your approval, or lands in your Drafts.<br>
Invitations to other people are off. Deletes go to the Trash.

**Built for mail from strangers.**<br>
Everything Claude reads is marked as someone else's words, not instructions.<br>
Hidden characters are stripped, and phishing tricks are called out.

**Tested where it counts.**<br>
311 offline tests on every change, integration tests against real mail and calendar servers,<br>
and hands-on runs against a live iCloud account for the quirks only Apple's servers have.

<br>

## New in 0.3.

</div>

<table>
<tr>
<td width="33%" valign="top"><b>One-click install</b><br>A Claude Desktop extension. Double-click, fill in a short form, done.</td>
<td width="33%" valign="top"><b>No server needed</b><br><code>--local</code> runs it on your computer for Claude Desktop and Claude Code.</td>
<td width="33%" valign="top"><b>Keychain storage</b><br><code>--store-password</code> keeps your app-specific password out of every file.</td>
</tr>
<tr>
<td width="33%" valign="top"><b>Find free time</b><br>Openings of any length within your hours. Travel time counts as busy.</td>
<td width="33%" valign="top"><b>Answer invitations</b><br>Accept, decline or maybe, for a whole series or a single date.</td>
<td width="33%" valign="top"><b>One date in a series</b><br>Move or cancel one occurrence and leave the rest alone.</td>
</tr>
<tr>
<td width="33%" valign="top"><b>Delivery you can trust</b><br>See whether each guest's invitation was sent, delivered or refused.</td>
<td width="33%" valign="top"><b>Search every folder</b><br>Archive, Sent, Junk and your own folders at once. Read 25 messages in one call.</td>
<td width="33%" valign="top"><b>Safe retries</b><br>A retried create never makes a duplicate. Stale mail ids are refused.</td>
</tr>
<tr>
<td width="33%" valign="top"><b>Scam warnings</b><br>Flags text that addresses an AI, asks for codes or says bank details changed.</td>
<td width="33%" valign="top"><b>A health check</b><br>Tests every service in one call and never shows a secret.</td>
<td width="33%" valign="top"><b>A smaller menu</b><br><code>TOOLS=essential</code> offers a core of 19 tools that clients choose from more reliably.</td>
</tr>
</table>

<br>

<picture>
  <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/epinethrone/icloud-mcp/main/assets/readme/how-dark.svg">
  <img src="https://raw.githubusercontent.com/epinethrone/icloud-mcp/main/assets/readme/how-light.svg" alt="How it works: Claude connects to icloud-mcp over OAuth and MCP. icloud-mcp talks to iCloud Mail, Calendar and Contacts over IMAP, SMTP, CalDAV and CardDAV. An optional Mac helper connects out to the server over pinned TLS and handles Reminders, Notes and iCloud Drive on your Mac." width="100%">
</picture>

<p align="center">Mail, Calendar and Contacts use Apple's standard protocols.<br>Reminders, Notes and iCloud Drive go through an optional helper on your Mac.<br>It connects out, so your Mac never opens a port.</p>

<br>

<div align="center">

## Choose how you run it.

</div>

| | **Claude Desktop** | **Claude Code** | **Your own server** |
|---|---|---|---|
| **Setup** | Double-click an extension | One command | Docker and an HTTPS address |
| **Works in** | Claude Desktop on this computer | Claude Code on this computer | Claude on the web, desktop and phone |
| **Outgoing mail** | Saved to Drafts for you to send | Saved to Drafts for you to send | Waits for your approval in a browser |
| **Guide** | [Install ›](#claude-desktop-in-one-click) | [Set up ›](#manual-setup-claude-code-or-claude-desktop-with-more-options) | [Quick start ›](#quick-start) |

<br>

## Run it locally (Claude Desktop and Claude Code)

The server runs on your own computer. Your client starts it when it needs it and talks to it directly, so there is no public address, tunnel, Docker or OAuth. Claude on the web and on your phone can't reach it; for that, [host it](#quick-start).

### Claude Desktop in one click

1. Download **`icloud-mcp-<version>.mcpb`** from the [latest release](https://github.com/epinethrone/icloud-mcp/releases/latest).
2. Double-click it, or drag it onto Claude Desktop → Settings → Extensions.
3. Fill in your Apple Account email, an [app-specific password](https://account.apple.com) (Claude Desktop keeps it in your system keychain), your name and your time zone, such as `Europe/Amsterdam`.

It starts approval-first: mail is saved to Drafts for you to send, and invitations to other people are off. This covers Mail, Calendar and Contacts. Reminders, Notes and iCloud Drive need the [Mac helper](#reminders-notes-and-icloud-drive-through-your-mac) 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.**

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

**2. Keep the password in your Keychain** (on a Mac). It asks for the app-specific password and never shows it on the command line:

```bash
uvx icloud-mcp-server --store-password
```

Not on a Mac? Add `ICLOUD_APP_PASSWORD=xxxx-xxxx-xxxx-xxxx` to the file instead. Any setting from [Configuration](#configuration) can go in it; `MCP_PUBLIC_URL` and `MCP_OWNER_PASSWORD` are not needed.

**3. Add it to your client** (needs [uv](https://docs.astral.sh/uv/)).

Claude Code:

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

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

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

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

> [!TIP]
> **Fewer tools, better choices.** Clients pick the right tool more reliably from a short list. Add `TOOLS=essential` for a core of 19: search, read and reply to mail; list events, find free time and create or update events; find contacts; the main Reminders, Notes and Drive tools; and the health check. Add exact names to it as needed, for example `TOOLS=essential,mail_move`.

**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, star