clover-mail-mcp

Clover Mail copies the mail that Apple Mail has already downloaded on your Mac into a local SQLite archive. From there you can search it, have a model of your choice summarize it, and let AI assistants such as Codex or Claude query it through a read-only Model Context Protocol server.

Status: alpha (0.2). In real use by its maintainer on macOS. Expect rough edges, and read Limitations before relying on it.

Why

• One memory for every inbox. School, work and personal accounts already meet in Apple Mail. Clover Mail reads that local cache, so it never asks for your mail passwords.

• Your archive stays on your Mac. The archive is a local file. Cloud services see data only when you turn on a feature that sends it, and every such feature is off by default.

• Bring your own AI. The archive is not tied to a model vendor or a chat client. Swap either one without touching your data.

• Ask in plain language. "What do I still need to reply to?" from Codex or Claude, without copying and pasting mail.

Related MCP server: proton-bridge-mcp

How it works

Apple Mail local cache  (read-only: never sends, moves, deletes or marks mail)
        │  clover-mail sync
        ▼
Local SQLite archive  ~/Library/Application Support/CloverMail/
        ├── keyword and natural-language search (CLI)
        ├── read-only MCP server ──► Codex · Claude · other MCP clients
        ├── optional AI analysis   (summary, translation, to-dos, deadlines)
        ├── optional daily brief   (stored locally; Feishu or email delivery)
        └── optional mirrors       (Feishu Base, Notion)

Features

Mail accounts. Anything Apple Mail syncs: Gmail, Outlook / Microsoft 365 (including many school and work accounts), iCloud and other IMAP accounts. Gmail and an Outlook-based university account are in daily use; other providers should work but are less tested.

AI providers. MiMo, any OpenAI-compatible Chat Completions endpoint, or Anthropic Messages. AI is optional: archive, search and MCP work without it.

Quick start

Requirements: macOS, Apple Mail with at least one downloaded message, and Python 3.11 or newer.

git clone https://github.com/clover475/clover-mail.git
cd clover-mail
python3 -m venv .venv
.venv/bin/python -m pip install -e '.[mcp]'

.venv/bin/clover-mail doctor           # counts accounts and mailboxes; prints no mail content
.venv/bin/clover-mail sync --days 3    # first real import: start small
.venv/bin/clover-mail search 'invoice' --days 3
.venv/bin/python scripts/check_mcp.py  # starts the MCP server and checks its tools

doctor needs Full Disk Access for the terminal you run it in (System Settings → Privacy & Security). That is a broad permission; grant it only to the app you actually use. Then follow the setup guide to add an AI provider, a schedule, or the optional integrations.

Connect an AI assistant

The MCP server runs on your Mac and talks to the client over stdio. Use the absolute path of the virtual environment created above.

Then ask, for example:

• "Use Clover Mail to summarize my mail from the last 3 days."

• "Did my school send anything important this week?"

• "What mail still needs action from me?"

• "Find the quotation email from the venue and show me its body."

• "Draft a reply to that message." (the assistant drafts; Clover Mail cannot send)

MCP tools

Every tool is annotated read-only. No tool sends, deletes, moves or edits mail, and none syncs or calls a model. Accounts appear as opaque IDs until you add an optional alias file with labels such as School or Gmail.

Privacy and security

• Read-only toward your mail. Clover Mail never writes to Apple Mail.

• Local by default. The archive, credentials (~/.config/clover-mail/) and alias map stay on your Mac with owner-only permissions.

• Each cloud feature is opt-in and separate. AI providers, Feishu, Notion, SMTP and remote images each receive only what Privacy describes, and only after you configure them.

• Your assistant is a data recipient too. When Codex, Claude or ChatGPT reads a tool result, that content goes to its provider. Running locally is not offline inference.

• Email is untrusted input. Tool results are marked as data, not instructions, to blunt prompt injection. AI-extracted dates and actions can still be wrong; check the original message.

Report vulnerabilities privately; see SECURITY.md.

Limitations

• macOS and Apple Mail only. Only messages Apple Mail has fully downloaded can be imported, and Apple's cache format is undocumented and may change.

• The MCP server is local (stdio). Regular ChatGPT web chat cannot use it.

• Unread state is not stored, so unread_only is not supported.

• No encrypted backup or multi-device sync of the archive; rely on FileVault and your normal backups.

• The Feishu and Notion adapters assume you create and own the target workspace.

Roadmap

Planned, roughly in this order. No dates are promised.

1. Per-source permissions. Grant each mailbox separately for the local archive, AI, Feishu, Notion and email, failing closed when nothing is granted.

2. Clearer sync reporting. Count messages skipped for missing permission or excluded folders, and recognise localized Gmail and Outlook spam and trash folder names.

3. Resilient scheduled runs. Skip destinations that are not enabled, keep going when one external service fails, and always store the daily brief before delivering it.

4. Simpler install. A single setup command that can also register the MCP server with installed clients.

5. Optional remote access. A documented, opt-in route for cloud ChatGPT via OpenAI's Secure MCP Tunnel, after a security review.

Suggestions are welcome in Issues.

Contributing

Small, focused pull requests are welcome. Use synthetic mail only: never attach real messages, archives, credentials or inbox screenshots. Start with CONTRIBUTING.md.

PYTHONPATH=src .venv/bin/python -m unittest discover -s tests

License

MIT © Clover Mail contributors