# macOS Mail MCP

An MCP server that discovers the mail accounts already configured in Apple Mail and reads them through Apple Mail automation. There is no accounts configuration file, and this project never writes a password or token to disk.

## Status and macOS boundary

macOS has no supported public API for enumerating the detailed incoming/outgoing server settings of every Internet Account. This server reads the current Sonoma accountd store at `~/Library/Accounts/Accounts4.sqlite` (and supports legacy Apple Mail `Accounts.plist` metadata when present), then obtains credentials only on demand with the macOS `security` tool. This is deliberately best-effort across Mail versions: test it against your particular Sonoma-or-newer Mail configuration before using it for production workflows.

The first mail operation may show an Automation prompt. Allow the ChatGPT desktop app to control **Mail**. Do not export/import passwords: Apple Mail performs its own account authentication, including provider OAuth.

Because Apple Mail stores its account database in a TCC-protected Library location, macOS also requires **Full Disk Access** for the application launching this server. In **System Settings → Privacy & Security → Full Disk Access**, add Terminal/iTerm if you launch it there; add your MCP desktop client (for example Codex) when that client launches it. Restart the launching application afterwards.

## Install

Requires macOS Sonoma+, Python 3.12+, and Apple Mail configured with IMAP-capable accounts.

```sh
git clone git@github.com:wherecodegetscooked/applemail-mcp.git
cd applemail-mcp
python3.12 -m venv .venv
.venv/bin/pip install -e '.[dev]'
.venv/bin/pytest
```

Run it over standard input/output (the normal MCP transport):

```sh
.venv/bin/macos-mail-mcp
```

Register the server with the ChatGPT desktop app / Codex:

```sh
codex mcp add macos-mail -- "$PWD/.venv/bin/macos-mail-mcp"
```

Restart the ChatGPT desktop app, then ask a new Codex task about your mail. Keep stdout reserved for MCP traffic; diagnostics go to stderr/the launchd log.

## Architecture

* `discovery.py` scans macOS account metadata every cycle. Account additions, removals, and server changes are picked up without a server restart.
* `apple_mail.py` uses macOS JXA automation to read the already-synced Apple Mail app. Apple Mail remains responsible for IMAP, SMTP, provider OAuth, retries, and credentials.
* `service.py` queries Apple Mail directly for current mail and search, then caches returned messages in SQLite/FTS5 for subsequent local reads.
* `store.py` contains message metadata, indexed bodies, and attachment metadata. It has no credentials. Attachment bytes are fetched only after `read_attachment`.

## Security and operations

The SQLite cache is private to the user at `~/Library/Application Support/macOS-Mail-MCP/mail.sqlite3`; protect the macOS login account and use FileVault. It can contain email content, so do not place it in a shared directory. Set `MAIL_MCP_DB` to another private path if required and `MAIL_MCP_LOG_LEVEL=DEBUG` for troubleshooting. Logs never include passwords.

Apple Mail performs provider authentication itself, so OAuth-only accounts such as Gmail can be queried without making their tokens available to this server. The server needs Full Disk Access for account discovery and Automation permission to read Mail.

## launchd

`launchd/com.example.macos-mail-mcp.plist` is a template. Replace both `REPLACE_ME` occurrences and the executable path with the virtualenv’s absolute executable path, then install it:

```sh
mkdir -p ~/Library/LaunchAgents
cp launchd/com.example.macos-mail-mcp.plist ~/Library/LaunchAgents/
launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/com.example.macos-mail-mcp.plist
```

For an stdio MCP server, launchd is normally used by a client-side bridge; most MCP desktop clients instead start the command themselves. Do not start two instances against the same SQLite file unless you have intentionally chosen that arrangement.

## Testing

Unit tests cover plist normalization, Keychain command handling, and SQLite FTS/incremental sync state. Integration testing should use a dedicated disposable IMAP account and an isolated `MAIL_MCP_DB`; it must never use a personal mailbox in CI. Run `pytest` locally after configuring that account.