Apple Mail
# Mail & Calendar
An MCP connector that runs as a Cloudflare Worker. It reads and searches iCloud
mail directly over IMAP/SMTP, creates synchronized drafts, resolves threaded
replies, and applies saved sender signatures. It does not launch Mail.app or
use AppleScript.
The same connector serves any number of Gmail and Google Calendar accounts:
Gmail tools that match Google's own Gmail connector, calendar tools that work
across every account, and one place to link them.
Added once to a Claude or ChatGPT account, it works in every app and device
signed in to that account, with nothing installed per machine. Clients that
can run shell commands, such as Claude Code, can also attach local files
through one-time upload links.
| Guide | |
| --- | --- |
| [docs/WORKER.md](docs/WORKER.md) | Deploy, connect clients, attachments, security |
| [docs/GOOGLE.md](docs/GOOGLE.md) | Link Gmail and Google Calendar accounts |
## Data
Account passwords and preferences are Worker secrets, uploaded by
`scripts/setup-worker.mjs` from this Mac's iCloud configuration (see
[docs/WORKER.md](docs/WORKER.md#deploy)). The primary address, sending
addresses, signatures and display names live in the Worker's KV, seeded on
first use and edited from chat. iCloud has no API for its alias settings, so
`list_sending_addresses` adds addresses found in Sent and suggests
custom-domain recipients from the inbox.
Drafts live on iCloud: each managed draft carries its ID in a header, so every
client sees the same drafts, revisions and send state.
## Develop
```sh
corepack enable
pnpm install --frozen-lockfile
pnpm test
pnpm test:worker
```
`src/worker/index.ts` is the Worker: OAuth, the account-linking pages
(`accounts.ts`), attachment uploads (`uploads.ts`) and the `MailSession`
Durable Object (`session.ts`) that serves MCP. `src/mcp/server.ts` combines the
iCloud tools (`src/icloud/`) with the Gmail and Calendar tools
(`src/google/`). The IMAP, SMTP, MIME and draft modules are under
`src/services/`.
`pnpm test:worker` runs the Worker in local workerd and walks the OAuth flow a
claude.ai connector performs. Real IMAP integration tests run against
GreenMail with `RUN_IMAP_IT=1 pnpm test:imap`.
## Attribution
The transport, MIME, and draft modules derive from
[sweetrb/apple-mail-mcp](https://github.com/sweetrb/apple-mail-mcp), under the MIT
license. The original copyright notice is preserved in [LICENSE](LICENSE).
TDQS
Scored across 61 tools
Each tool targets a distinct resource and action, with detailed 'use when' and 'do not use when' guidance that clearly differentiates similar-sounding tools like send-email vs send-serial-email vs send-draft, or search-messages vs list-messages. No two tools overlap in purpose.
All 61 tools follow a consistent verb_noun snake_case pattern (e.g., delete-template, list-messages, batch-flag-messages). The naming is uniform and predictable, making it easy to infer tool behavior from its name.
With 61 tools, the count is far above the typical well-scoped range of 3-15. While each tool has a clear purpose, the high number—especially the proliferation of batch variants and diagnostic tools—makes the surface feel bloated and potentially overwhelming for an agent.
The tool set covers virtually every aspect of email management: sending, receiving, drafting, replying, forwarding, mailbox CRUD, rule management, template management, smart mailboxes, contacts, attachments, scheduling, and diagnostics. There are no obvious gaps for a consumer email client.