# Apple Mail MCP Server

[![Tests](https://github.com/s-morgan-jeffries/apple-mail-mcp/actions/workflows/test.yml/badge.svg)](https://github.com/s-morgan-jeffries/apple-mail-mcp/actions/workflows/test.yml)
[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

An MCP server that provides programmatic access to Apple Mail, enabling AI assistants like Claude to read, send, search, and manage emails on macOS.

> ⚠️ **Pre-1.0 — expect breaking changes.** The MCP tool surface (tool names, parameters, return shapes) is still evolving as the project matures. Pin to a specific version (for example, `apple-mail-mcp==0.8.1`) and review the [CHANGELOG](CHANGELOG.md) before upgrading.

## Tools (25)

**Core:** list_mailboxes, search_messages, get_messages, update_message
**Drafts lifecycle (v2 — verb-split):** draft_create, draft_update, draft_delete, draft_send
**Sending:** email_send_html
**Mailbox CRUD:** create_mailbox, update_mailbox, delete_mailbox
**Attachments & Management:** save_attachments, delete_messages
**Discovery & Rules:** list_accounts, list_rules, get_thread, create_rule, update_rule, delete_rule
**Templates:** list_templates, get_template, save_template, delete_template, render_template

See [docs/reference/TOOLS.md](docs/reference/TOOLS.md) for full parameter and return-shape documentation.

## Prerequisites

- macOS 10.15 (Catalina) or later
- Python 3.10 or later
- Apple Mail configured with at least one account
- [uv](https://docs.astral.sh/uv/) (recommended) or pip

## Installation

```bash
# From source (recommended for development)
git clone https://github.com/s-morgan-jeffries/apple-mail-mcp.git
cd apple-mail-mcp
uv sync --dev
```

## Configuration

Add to your Claude Desktop config (`~/Library/Application Support/Claude/claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "apple-mail": {
      "command": "uv",
      "args": ["--directory", "/path/to/apple-mail-mcp", "run", "python", "-m", "apple_mail_mcp.server"]
    }
  }
}
```

## Running as a fleet daemon

Where many agent sessions share one Mail, the server can instead run as one
resident daemon, with a thin stdio proxy per session. The stdio entry above is
unchanged, and a client that runs its own server needs neither.

- `mail-serve` is the daemon. It serves the tools over streamable HTTP on
  `127.0.0.1:41108`, loopback only (`--port` to change it; 41108 is
  provisional). It runs under a process supervisor (pm2 in the fleet that
  runs it), launched from this repo as `uv run --project <this repo> mail-serve`.
- The daemon tends Mail's compose windows: at start, every 15 minutes, and
  soon after a composition fails and leaves its window open, it closes the
  windows this server opened and left (salvaged to Drafts, or discarded when
  empty), and only those; every other window is left and counted in the
  audit log. `--tend-interval SECONDS` changes the interval, and 0 turns it
  off (docs/research/compose-window-tending.md).
- The daemon quits and relaunches Mail on its own. Every 5 minutes it asks
  Mail one cheap question under the Mail lock; when Mail leaves two in a row
  unanswered for 20 seconds, it restarts Mail, and it also restarts Mail once
  a day at 04:00 local time (a day whose hour passed while the daemon was down
  is skipped, and the daily one waits while a send or draft is being
  composed). It also restarts Mail before it wedges, when it has kept most
  of a CPU core busy for 15 minutes or its memory footprint has stayed
  above 3 GiB on two checks; these too wait for a composition. A restart
  holds the Mail lock throughout, asks Mail to quit,
  then sends SIGTERM and SIGKILL if Mail's process has not exited, relaunches
  it in the background with `open -g`, and waits for it to answer; once Mail
  answers, it runs a tending pass rather than waiting out tending's back-off.
  It never launches a Mail that was not running, never restarts Mail more
  than once an hour, and logs every restart to the audit log as
  `restart_mail`.
  `--mail-probe-interval SECONDS` changes the probe interval, and 0 turns
  probing and both kinds of restart off; `--mail-restart-hour HOUR` moves the
  daily one. The stdio server never restarts Mail.
- Restarting the daemon is a deploy. A session already connected through its
  proxy reaches the new daemon on its next call; changed instructions reach a
  session when it next starts.
- `mail-proxy` is what a session launches:
  `uv run --project <this repo> mail-proxy`.
  It takes no arguments and declares nothing of its own. Every listing and
  call, confirmation prompts included, is forwarded to the daemon, and the
  daemon's instructions are fetched when the proxy starts.
  `APPLE_MAIL_SERVER_URL` points it at a daemon elsewhere.
- Registering `mail-proxy` in a session's MCP configuration is the operator's
  edit.

## Permissions

On first run, macOS will prompt for Automation access. Grant permission in:
**System Settings > Privacy & Security > Automation > Terminal (or your IDE)**

## Optional: faster search via IMAP

`search_messages` works out of the box via AppleScript. For large mailboxes (thousands of messages), AppleScript's `whose` clause can take 1–5 seconds per query. If you want faster server-side search, you can enable IMAP delegation per account by adding a Keychain entry.

**How it works.** If a Keychain entry exists for an account, the server uses IMAP (fast, server-side SEARCH). Otherwise — or on any IMAP failure (offline, wrong password, timeout) — it silently falls back to AppleScript. You never lose functionality; you only gain speed when IMAP is configured and reachable. No config flags, no environment variables; the Keychain entry's presence is the opt-in.

**One-time setup per account.**

1. Generate an app-specific password at your provider. The procedure varies:
   - **iCloud:** [appleid.apple.com/account/manage](https://appleid.apple.com/account/manage) → App-Specific Passwords. Requires 2FA on your Apple ID (default).
   - **Gmail:** [myaccount.google.com/apppasswords](https://myaccount.google.com/apppasswords). Requires 2-Step Verification on your Google account.
   - **Yahoo / Fastmail / AOL:** generate an app password in the provider's account-security settings.

2. Run the `setup-imap` subcommand. It prompts for the password (no echo), writes the Keychain entry, and verifies by connecting:
   ```bash
   apple-mail-mcp setup-imap --account iCloud
   ```
   Substitute the Mail.app account name exactly — whatever it's labeled in Mail.app (e.g. `iCloud`, `Gmail`, `"Yahoo!"`). The CLI:
   - looks up the account's primary email from Mail.app (override with `--email`),
   - prompts via `getpass` so the password never lands in shell history,
   - writes to Keychain at `apple-mail-mcp.imap.<account>` (idempotent — re-running with a new password updates the existing entry),
   - opens an IMAP connection and runs a real LOGIN to confirm the password works. On rejection it rolls back the Keychain entry so you can retry without leaving a broken item behind.

3. If you see a one-time "security wants to use the 'login' keychain" prompt on the next IMAP-backed call, click **Always Allow**.

To remove the entry later: `apple-mail-mcp setup-imap --account iCloud --uninstall`.

**Verifying the setup.** The `setup-imap` command does this for you. If you want to spot-check post-hoc:
```bash
uv run python -c "from apple_mail_mcp.mail_connector import AppleMailConnector; \
    print(AppleMailConnector().search_messages(account='<ACCOUNT_NAME>', limit=1))"
```
If IMAP is working, the call returns in ~1 second. If it logs a WARNING about falling back (visible with `--log-level=DEBUG`), check that the account name matches Mail.app's account name exactly and that the email in your Keychain entry matches what `email addresses of account` returns.

**Known provider quirks.**

- **iCloud:** the IMAP server accepts `@icloud.com` / `@me.com` aliases as LOGIN username, not the Apple ID email. The server (and `setup-imap`) reads `email addresses of account` from Mail.app for that reason.
- **Yahoo:** app passwords have been progressively deprecated; the option may not be available for all accounts. If Yahoo's account-security page doesn't show the option, IMAP setup isn't possible for that account and AppleScript is the only path.
- **Gmail:** requires 2-Step Verification enabled. If your Google Workspace admin has disabled app passwords at the tenant level, IMAP setup isn't possible for that account.
- **Gmail thread retrieval — All Mail visibility tradeoff.** `find_thread_members` (used internally by thread-aware queries) is fastest when `[Gmail]/All Mail` is exposed over IMAP — that path is ~5 round-trips, mailbox-count-independent. Many users hide All Mail (Gmail Settings → Forwarding and POP/IMAP → Folder size limits → "Do not show in IMAP") because it duplicates every message. When hidden, the connector falls back to a per-mailbox X-GM-THRID iteration (still ~6× faster than the universal BFS, but proportional to your label count — ~25s on a 92-label account). Expose All Mail if you want the headline speed; keep it hidden if you prefer the cleaner IMAP folder list.

**Write operations** (`draft_create`, `draft_update`, `draft_send`) always use AppleScript regardless of IMAP configuration — these need Mail.app's compose UI.

## Development

```bash
# Setup
uv sync --dev

# Common commands
make test              # Run unit tests
make lint              # Lint with ruff
make typecheck         # Type check with mypy
make check-all         # All checks (lint, typecheck, test, complexity, version-sync, parity)
make coverage          # Coverage report
make test-integration  # Integration tests (requires Mail.app)

# Validation scripts
./scripts/check_version_sync.sh          # Version consistency
./scripts/check_client_server_parity.sh  # Connector-server alignment
./scripts/check_complexity.sh            # Cyclomatic complexity
./scripts/check_applescript_safety.sh    # AppleScript safety audit
```

### Branch Convention

`{type}/issue-{num}-{description}` — e.g., `feature/issue-42-thread-support`

## Architecture

```
server.py + tools/ (FastMCP tools — thin orchestration)
  -> mail_connector.py (AppleScript bridge — domain logic)
     -> subprocess.run(["osascript", ...])
        -> Apple Mail.app
```

- **server.py** — the FastMCP instance, the connector, confirmation and the error envelope
- **tools/** — the MCP tools, one module per domain: input validation, gates, response formatting
- **mail_connector.py** — All AppleScript generation and execution
- **security.py** — Input sanitization, audit logging, confirmation flows
- **utils.py** — Pure functions: escaping, parsing, validation
- **exceptions.py** — Typed exception hierarchy

## Security

- Local execution only (no cloud processing)
- Uses existing Mail.app authentication (no credential storage)
- All inputs sanitized and AppleScript-escaped
- Destructive operations require confirmation
- Operation audit logging
- See [SECURITY.md](SECURITY.md) for policy and [docs/SECURITY.md](docs/SECURITY.md) for detailed analysis

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md) for development workflow, coding standards, and PR process.

## License

[MIT](LICENSE)