Skip to content
Back to search

apple-mail-fast-mcp

πŸ€– MCP server for Apple Mail - Manage emails with AI using Claude Desktop. Search, send, organize mail with natural language.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/s-morgan-jeffries--apple-mail-fast-mcp/badge.svg)](/listings/s-morgan-jeffries--apple-mail-fast-mcp)

HTML

<a href="/listings/s-morgan-jeffries--apple-mail-fast-mcp"><img src="/api/listings/s-morgan-jeffries--apple-mail-fast-mcp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Claude Desktop β€” install from file (`.mcpb`)

The lowest-friction path for Claude Desktop: grab the `apple-mail-fast-mcp-<version>.mcpb` bundle from the [Releases](https://github.com/s-morgan-jeffries/apple-mail-fast-mcp/releases) page and open it (or drag it into **Settings β†’ Extensions**). Claude Desktop manages Python and dependencies for you via `uv` β€” no manual venv, no config JSON to hand-edit. macOS only.

To build the bundle yourself: `./scripts/build-mcpb.sh` β†’ `dist/apple-mail-fast-mcp-<version>.mcpb` (requires Node for the `mcpb` packer).

Claude Code β€” install as a plugin

One command in Claude Code, no config JSON:

/plugin marketplace add s-morgan-jeffries/apple-mail-fast-mcp
/plugin install apple-mail-fast@apple-mail-fast-mcp

Claude Code launches the server via `uv run` from the plugin directory (resolves dependencies from the bundled `pyproject.toml`/`uv.lock` β€” no PyPI needed), so you only need `uv` installed. macOS only. See [`docs/reference/TOOLS.md`](docs/reference/TOOLS.md) for IMAP setup and the read/write split.

pip / uvx (any MCP client)

Published on [PyPI](https://pypi.org/project/apple-mail-fast-mcp/):

uvx apple-mail-fast-mcp          # zero-install, run on demand
pip install apple-mail-fast-mcp  # or install the console script

Then point your MCP client at it β€” the config is a one-liner (no absolute paths):

{
  "mcpServers": {
    "apple-mail": { "command": "uvx", "args": ["apple-mail-fast-mcp"] }
  }
}

From source (development)

git clone https://github.com/s-morgan-jeffries/apple-mail-fast-mcp.git
cd apple-mail-fast-mcp
uv sync --dev

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/marketplace.json Β· Manifest Β· 26 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. {
  2. "$schema": "https://anthropic.com/claude-code/marketplace.schema.json",
  3. "name": "apple-mail-fast-mcp",
  4. "version": "0.11.0",
  5. "description": "Apple Mail for Claude Code β€” fast, security-first email management via MCP (macOS)",
  6. "owner": {
  7. "name": "Morgan Jeffries"
  8. },
  9. "plugins": [
  10. {
  11. "name": "apple-mail-fast",
  12. "displayName": "Apple Mail (Fast MCP)",
  13. "description": "Search, read, organize, draft, templates, rules, and inbox stats for Apple Mail β€” with an IMAP fast path and a security-first design. macOS only.",
  14. "version": "0.11.0",
  15. "source": "./",
  16. "author": {
  17. "name": "Morgan Jeffries"
  18. },
  19. "homepage": "https://github.com/s-morgan-jeffries/apple-mail-fast-mcp",
  20. "repository": "https://github.com/s-morgan-jeffries/apple-mail-fast-mcp",
  21. "license": "MIT",
  22. "keywords": ["mcp", "apple-mail", "email", "macos", "imap"],
  23. "category": "productivity"
  24. }
  25. ]
  26. }
README.md Β· README Β· 267 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # Apple Mail MCP Server
  2. [![Tests](https://github.com/s-morgan-jeffries/apple-mail-fast-mcp/actions/workflows/test.yml/badge.svg)](https://github.com/s-morgan-jeffries/apple-mail-fast-mcp/actions/workflows/test.yml)
  3. [![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
  4. [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
  5. An MCP server that provides programmatic access to Apple Mail, enabling AI assistants like Claude to read, send, search, and manage emails on macOS.
  6. > ⚠️ **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-fast-mcp==0.11.0`) and review the [CHANGELOG](CHANGELOG.md) before upgrading.
  7. ## Tools (25)
  8. Grouped by lifecycle (11 read-only, 14 mutating):
  9. - **Discovery** β€” `list_accounts`, `list_mailboxes`, `list_rules`, `list_templates`: enumerate what's configured (no external cache β€” call per account).
  10. - **Read** β€” `search_messages`, `get_messages`, `get_thread`, `get_statistics`, `get_attachment_content`, `get_template`, `render_template`: read messages/threads, aggregate inbox stats, pull an attachment's content inline, and render templates.
  11. - **Message actions** β€” `update_message` (read/flag/move in one pass), `delete_messages` (β†’ Trash), `save_attachments` (to disk, byte-capped).
  12. - **Drafts** β€” `create_draft` (new / reply / forward, optionally `send_now`), `update_draft`, `delete_draft`.
  13. - **Mailbox CRUD** β€” `create_mailbox`, `update_mailbox` (rename or move), `delete_mailbox`.
  14. - **Rules** β€” `create_rule`, `update_rule`, `delete_rule`.
  15. - **Templates (write)** β€” `save_template`, `delete_template`.
  16. Destructive operations (`delete_*`, `create_rule` with move/forward/delete actions, `create_draft` with `send_now=true`) prompt for confirmation via MCP elicitation. See [docs/reference/TOOLS.md](docs/reference/TOOLS.md) for full parameters and return shapes.
  17. ## Prerequisites
  18. - macOS 10.15 (Catalina) or later
  19. - Python 3.10 or later
  20. - Apple Mail configured with at least one account
  21. - [uv](https://docs.astral.sh/uv/) (recommended) or pip
  22. ## Installation
  23. ### Claude Desktop β€” install from file (`.mcpb`)
  24. The lowest-friction path for Claude Desktop: grab the `apple-mail-fast-mcp-<version>.mcpb`
  25. bundle from the [Releases](https://github.com/s-morgan-jeffries/apple-mail-fast-mcp/releases)
  26. page and open it (or drag it into **Settings β†’ Extensions**). Claude Desktop manages Python
  27. and dependencies for you via `uv` β€” no manual venv, no config JSON to hand-edit. macOS only.
  28. To build the bundle yourself: `./scripts/build-mcpb.sh` β†’ `dist/apple-mail-fast-mcp-<version>.mcpb`
  29. (requires Node for the `mcpb` packer).
  30. ### Claude Code β€” install as a plugin
  31. One command in Claude Code, no config JSON:
  32. ```
  33. /plugin marketplace add s-morgan-jeffries/apple-mail-fast-mcp
  34. /plugin install apple-mail-fast@apple-mail-fast-mcp
  35. ```
  36. Claude Code launches the server via `uv run` from the plugin directory (resolves dependencies
  37. from the bundled `pyproject.toml`/`uv.lock` β€” no PyPI needed), so you only need `uv` installed.
  38. macOS only. See [`docs/reference/TOOLS.md`](docs/reference/TOOLS.md) for IMAP setup and the
  39. read/write split.
  40. ### pip / uvx (any MCP client)
  41. Published on [PyPI](https://pypi.org/project/apple-mail-fast-mcp/):
  42. ```bash
  43. uvx apple-mail-fast-mcp # zero-install, run on demand
  44. pip install apple-mail-fast-mcp # or install the console script
  45. ```
  46. Then point your MCP client at it β€” the config is a one-liner (no absolute paths):
  47. ```json
  48. {
  49. "mcpServers": {
  50. "apple-mail": { "command": "uvx", "args": ["apple-mail-fast-mcp"] }
  51. }
  52. }
  53. ```
  54. ### From source (development)
  55. ```bash
  56. git clone https://github.com/s-morgan-jeffries/apple-mail-fast-mcp.git
  57. cd apple-mail-fast-mcp
  58. uv sync --dev
  59. ```
  60. ## Configuration
  61. > Skip this section if you installed the `.mcpb` bundle β€” it wires up Claude Desktop for you.
  62. > The manual config below is for source installs.
  63. Add to your Claude Desktop config (`~/Library/Application Support/Claude/claude_desktop_config.json`). `uv sync` installs a console script at `.venv/bin/apple-mail-fast-mcp`; point Claude Desktop at its **absolute path** β€” it's the most reliable form under Claude Desktop's restricted spawn environment (no reliance on `uv` being on `PATH`):
  64. ```json
  65. {
  66. "mcpServers": {
  67. "apple-mail": {
  68. "command": "/path/to/apple-mail-fast-mcp/.venv/bin/apple-mail-fast-mcp"
  69. }
  70. }
  71. }
  72. ```
  73. (Equivalent alternative if you prefer driving it through uv: `"command": "uv", "args": ["--directory", "/path/to/apple-mail-fast-mcp", "run", "apple-mail-fast-mcp"]`.)
  74. ### Optional: split read / write servers
  75. Claude Desktop prompts per-tool for permission. If you want to **batch-approve the 9 read tools** (list / search / get) and still gate the 14 mutating tools per call, run the connector twice β€” once with `--read-only`, once without β€” under two separate `mcpServers` entries:
  76. ```json
  77. {
  78. "mcpServers": {
  79. "apple-mail-read": {
  80. "command": "/path/to/apple-mail-fast-mcp/.venv/bin/apple-mail-fast-mcp",
  81. "args": ["--read-only"]
  82. },
  83. "apple-mail-write": {
  84. "command": "/path/to/apple-mail-fast-mcp/.venv/bin/apple-mail-fast-mcp"
  85. }
  86. }
  87. }
  88. ```
  89. The `--read-only` server exposes only the 9 read tools, so Claude Desktop's per-server permission UI naturally groups them. The full server still gates writes individually. Trade-off: 2Γ— connector processes. See [`docs/reference/TOOLS.md`](docs/reference/TOOLS.md) for the per-tool classification and a note on MCP annotation hints (`readOnlyHint` / `destructiveHint` / `idempotentHint`) which forward-compatible hosts may use to provide the same UX without the split.
  90. ## Permissions
  91. On first run, macOS will prompt for Automation access. Grant permission in:
  92. **System Settings > Privacy & Security > Automation > Terminal (or your IDE)**
  93. ## Optional: faster search via IMAP
  94. `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.
  95. **How it works.** If credentials exist 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. The normal opt-in is a Keychain entry (below); an environment-variable fallback ([further down](#environment-variable-fallback-uvx--headless--ci)) covers contexts where the Keychain isn't usable.
  96. **One-time setup per account β€” the `setup-imap` subcommand walks you through it:**
  97. ```bash
  98. apple-mail-fast-mcp setup-imap --account iCloud
  99. ```
  100. Substitute the Mail.app account name exactly β€” whatever it's labeled in Mail.app (e.g. `iCloud`, `Gmail`, `"Yahoo!"`). The guided flow (#384):
  101. - **detects your provider** from the account's IMAP host and points you at the right app-password page β€” **iCloud** ([account.apple.com](https://account.apple.com/account/manage) β†’ App-Specific Passwords), **Gmail** ([myaccount.google.com/apppasswords](https://myaccount.google.com/apppasswords)), **Yahoo**, **Outlook**, **Fastmail** (generic guidance for anything else) β€” with the provider's 2FA steps, and **offers to open the page** in your browser;
  102. - explains that this is a **scoped, revocable app-specific password** β€” limited to that one account β€” unlike granting full disk access;
  103. - looks up the account's primary email from Mail.app (override with `--email`, which is **persisted** so runtime uses the same login β€” see the iCloud quirk below);
  104. - reads the IMAP **host and port** from Mail.app; if either is wrong β€” some institutional servers (e.g. Zimbra) scriptably misreport the port as `143` for a server actually on `993`, so the implicit-TLS handshake fails with `WRONG_VERSION_NUMBER` β€” override with `--host` / `--port <993>`, which are **persisted** so runtime connects to the same coordinates (#405);
  105. - prompts via `getpass` so the password never lands in shell history;
  106. - writes to Keychain at `apple-mail-fast-mcp.imap.<account>` (idempotent β€” re-running with a new password updates the entry; pre-rename `apple-mail-mcp.imap.` entries still resolve via a read-through fallback removed at 1.0.0);
  107. - opens an IMAP connection and runs a real LOGIN to confirm the password works. On rejection it **rolls back the Keychain entry and lets you paste again** (up to 3 tries) so a bad password never leaves a broken item behind.
  108. If you see a one-time "security wants to use the 'login' keychain" prompt on the next IMAP-backed call, click **Always Allow**.
  109. To remove the entry later: `apple-mail-fast-mcp setup-imap --account iCloud --uninstall`.
  110. ### Environment-variable fallback (uvx / headless / CI)
  111. Some contexts have no usable Keychain: `uvx` runs (ephemeral binary paths break the Keychain ACL, causing re-prompts or failures), Docker / CI (no Keychain at all), and background services (the ACL prompt blocks forever with no UI attached). For those, you can supply the IMAP password via an environment variable instead:
  112. ```
  113. APPLE_MAIL_MCP_IMAP_PASSWORD_<SUFFIX>
  114. ```
  115. `<SUFFIX>` is the Mail.app account name **uppercased**, with each run of non-alphanumeric characters collapsed to a single underscore and leading/trailing underscores trimmed:
  116. | Account name | Environment variable |
  117. |---|---|
  118. | `iCloud` | `APPLE_MAIL_MCP_IMAP_PASSWORD_ICLOUD` |
  119. | `Gmail` | `APPLE_MAIL_MCP_IMAP_PASSWORD_GMAIL` |
  120. | `Yahoo!` | `APPLE_MAIL_MCP_IMAP_PASSWORD_YAHOO` |
  121. | `My Gmail` | `APPLE_MAIL_MCP_IMAP_PASSWORD_MY_GMAIL` |
  122. When set to a non-empty value, the env var is used **in preference to** any Keychain entry for that account (it's checked first, with no `security` shell-out). An empty or whitespace-only value is ignored and the Keychain path is used. The lookup composes with the name↔UUID fallback, so an env var keyed on the account name is still found when a caller passes the account's UUID.
  123. > ⚠️ **Security tradeoff.** Environment variables are far less private than the Keychain β€” they're visible via `ps -E`, `launchctl getenv`, `/proc`-style introspection, and process crash dumps, and they're easy to leak into logs or shell history. **Use this only when the Keychain genuinely isn't an option** (uvx, Docker, CI, headless). For Claude Desktop and standard local installs, stick with `setup-imap` + Keychain.
  124. >
  125. > Caveat: the name→suffix mapping isn't reversible — `Yahoo!` and `Yahoo` both map to `YAHOO`, and an account name with no ASCII letters/digits has no env-var form (use the Keychain for those).
  126. **Verifying the setup.** The `setup-imap` command does this for you. If you want to spot-check post-hoc:
  127. ```bash
  128. uv run python -c "from apple_mail_fast_mcp.mail_connector import AppleMailConnector; \
  129. print(AppleMailConnector().search_messages(account='<ACCOUNT_NAME>', limit=1))"
  130. ```
  131. 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.
  132. **Known provider quirks.**
  133. - **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. If your iCloud Apple ID is a *third-party* address (e.g. a `@gmail.com` Apple ID) **and** Mail.app reports no `@icloud.com` address for the account, auto-detection can't find the right login β€” `setup-imap` will fail with a hint to re-run with `--email <your @icloud.com/@me.com address>`. That `--email` value is **persisted** (in `~/.apple_mail_mcp/imap_login_overrides.json`) so runtime resolution uses the same login (#341). It's a general override β€” use it for any account whose auto-detected IMAP login is wrong.
  134. - **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.
  135. - **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.
  136. - **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.
  137. **Compose operations** can use IMAP APPEND for drafts and SMTP for `send_now=true`
  138. when the required credentials and account/seed information are available. Eligible
  139. calls fall back to AppleScript when those paths cannot engage. See the
  140. [architecture reference](docs/reference/ARCHITECTURE.md) for dispatch details.
  141. ## Development
  142. ```bash
  143. # Setup
  144. uv sync --dev
  145. # Common commands
  146. make test # Run unit tests
  147. make lint # Lint with ruff
  148. make typecheck # Type check with mypy
  149. make check-all # All checks (lint, typecheck, test, complexity, version-sync, parity)
  150. make coverage # Coverage report
  151. make test-integration # Integration tests (requires Mail.app)
  152. # Validation scripts
  153. ./scripts/check_version_sync.sh # Version consistency
  154. ./scripts/check_client_server_parity.sh # Connector-server alignment
  155. ./scripts/check_complexity.sh # Cyclomatic complexity
  156. ./scripts/check_applescript_safety.sh # AppleScript safety audit
  157. ```
  158. ### Branch Convention
  159. `{type}/issue-{num}-{description}` β€” e.g., `feature/issue-42-thread-support`
  160. ## Architecture
  161. ```
  162. server.py (FastMCP tools β€” thin orchestration, validation, elicitation gates)
  163. -> mail_connector.py (dispatch + domain logic)
  164. -> AppleScript path: subprocess.run(["osascript", ...]) -> Apple Mail.app (universal baseline)
  165. -> IMAP fast path: imap_connector.py -> the account's IMAP server (when hinted + Keychain creds)
  166. ```
  167. **Dispatch model.** AppleScript is the baseline for many operations. When a read/mutation call
  168. supplies an `account` (and, where relevant, `mailbox`) hint **and** the account has IMAP credentials,
  169. the connector can take a server-side IMAP fast path. Eligible failures use AppleScript fallback
  170. where available; some operations require IMAP, and fallback can be slower or less complete. See
  171. [docs/reference/ARCHITECTURE.md](docs/reference/ARCHITECTURE.md) for the full dispatch model, the
  172. dual-emit message-ID scheme, the drafts lifecycle, and the IMAP thread tiers.
  173. - **server.py** β€” MCP tool registration, input validation, confirmation (elicitation) gates, response formatting
  174. - **mail_connector.py** β€” AppleScript generation/execution + IMAP-fast-path dispatch
  175. - **imap_connector.py** β€” IMAP client + connection pool (search, fetch, bulk-mutation fast paths)
  176. - **security.py** β€” Input sanitization, audit logging, confirmation flows
  177. - **utils.py** β€” Pure functions: escaping, parsing, validation
  178. - **exceptions.py** β€” Typed exception hierarchy
  179. ## Security
  180. - Local execution only (no cloud processing)
  181. - Uses existing Mail.app authentication; IMAP app-passwords (opt-in) live in the macOS Keychain, never in the repo or config
  182. - All inputs sanitized and AppleScript-escaped (defense against AppleScript injection)
  183. - Destructive operations require user confirmation via MCP elicitation; rate limits + audit logging on top
  184. - `save_attachments` is byte-capped (per-attachment + aggregate) against disk-fill DoS
  185. Docs:
  186. - [SECURITY.md](SECURITY.md) β€” vulnerability-reporting policy
  187. - [docs/SECURITY.md](docs/SECURITY.md) β€” user-facing security posture & privacy
  188. - [docs/guides/THREAT_MODEL.md](docs/guides/THREAT_MODEL.md) β€” STRIDE trust-boundary analysis
  189. - [docs/guides/SECURITY_CHECKLIST.md](docs/guides/SECURITY_CHECKLIST.md) β€” per-feature contributor checklist
  190. ## Contributing
  191. See [CONTRIBUTING.md](CONTRIBUTING.md) for development workflow, coding standards, and PR process.
  192. For agent-assisted development, start with [AGENTS.md](AGENTS.md) and the
  193. [Codex setup guide](docs/guides/CODEX.md).
  194. ## License
  195. [MIT](LICENSE)

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.