Skip to content
Back to search

apple-mail-mcp

MCP serverGitHubIncomplete

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/patrickfreyer--apple-mail-mcp/badge.svg)](/listings/patrickfreyer--apple-mail-mcp)

HTML

<a href="/listings/patrickfreyer--apple-mail-mcp"><img src="/api/listings/patrickfreyer--apple-mail-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.

**Prerequisites:** macOS with Apple Mail configured, Python 3.10+, and [uv](https://docs.astral.sh/uv/) (the plugin and uvx installs launch the server with `uvx`)

Claude Code Plugin (Recommended)

Two commands — gets you the MCP server, `/email-management` slash command, and the Email Management Expert skill:

claude plugin marketplace add patrickfreyer/apple-mail-mcp
claude plugin install apple-mail@apple-mail-mcp

Then restart Claude Code.

Other Install Methods

<details> <summary><strong>uvx (zero install, MCP server only)</strong></summary>

claude mcp add apple-mail -- uvx mcp-apple-mail

Or for Claude Desktop (`~/Library/Application Support/Claude/claude_desktop_config.json`):

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

</details>

<details> <summary><strong>pip install (MCP server only)</strong></summary>

pip install mcp-apple-mail
claude mcp add apple-mail -- mcp-apple-mail

</details>

<details> <summary><strong>npx skills (skill only, for Claude Code, Codex, Cursor and other agents)</strong></summary>

Installs the Email Management Expert skill via the open [skills CLI](https://skills.sh). The skill does not include the MCP server, so install that too (e.g. with uvx above):

npx skills add patrickfreyer/apple-mail-mcp
claude mcp add apple-mail -- uvx mcp-apple-mail

Add `-g` to install the skill globally, or `-a <agent>` to target a specific agent.

</details>

<details> <summary><strong>Claude Desktop MCPB</strong></summary>

1. Download the latest `apple-mail-mcp-vX.Y.Z.mcpb` from [Releases](https://github.com/patrickfreyer/apple-mail-mcp/releases) 2. Open Claude Desktop → Settings → Developer → MCP Servers → Install from file 3. Select the `.mcpb` file and grant Mail.app permissions

</details>

<details> <summary><strong>Manual setup</strong></summary>

git clone https://github.com/patrickfreyer/apple-mail-mcp.git
cd apple-mail-mcp/plugin
python3 -m venv venv
venv/bin/pip install -r requirements.txt

claude mcp add apple-mail -- /bin/bash $(pwd)/start_mcp.sh

</details>

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 · 22 lines
  1. {
  2. "name": "apple-mail-mcp",
  3. "owner": {
  4. "name": "Patrick Freyer",
  5. "email": "freyer.patrick@bcg.com"
  6. },
  7. "metadata": {
  8. "description": "Apple Mail MCP — natural language email management for Claude Code",
  9. "version": "1.0.0"
  10. },
  11. "plugins": [
  12. {
  13. "name": "apple-mail",
  14. "source": "./plugin",
  15. "description": "Natural language interface for Apple Mail on macOS: search, read, compose, triage, organize, and analyze email with 28 MCP tools and an expert email management skill",
  16. "version": "3.4.0",
  17. "author": {
  18. "name": "Patrick Freyer"
  19. }
  20. }
  21. ]
  22. }
README.md · README · 341 lines
  1. # Apple Mail MCP Server
  2. <!-- mcp-name: io.github.patrickfreyer/apple-mail -->
  3. [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
  4. [![PyPI](https://img.shields.io/pypi/v/mcp-apple-mail)](https://pypi.org/project/mcp-apple-mail/)
  5. [![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
  6. [![MCP](https://img.shields.io/badge/MCP-Compatible-green.svg)](https://modelcontextprotocol.io)
  7. [![GitHub stars](https://img.shields.io/github/stars/patrickfreyer/apple-mail-mcp?style=social)](https://github.com/patrickfreyer/apple-mail-mcp/stargazers)
  8. ## Star History
  9. <a href="https://star-history.com/#patrickfreyer/apple-mail-mcp&Date">
  10. <picture>
  11. <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/svg?repos=patrickfreyer/apple-mail-mcp&type=Date&theme=dark" />
  12. <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/svg?repos=patrickfreyer/apple-mail-mcp&type=Date" />
  13. <img alt="Star History Chart" src="https://api.star-history.com/svg?repos=patrickfreyer/apple-mail-mcp&type=Date" />
  14. </picture>
  15. </a>
  16. An MCP server that gives AI assistants full access to Apple Mail -- read, search, compose, organize, and analyze emails via natural language. Built with [FastMCP](https://github.com/jlowin/fastmcp).
  17. ## Quick Install
  18. **Prerequisites:** macOS with Apple Mail configured, Python 3.10+, and [uv](https://docs.astral.sh/uv/) (the plugin and uvx installs launch the server with `uvx`)
  19. ### Claude Code Plugin (Recommended)
  20. Two commands — gets you the MCP server, `/email-management` slash command, and the Email Management Expert skill:
  21. ```bash
  22. claude plugin marketplace add patrickfreyer/apple-mail-mcp
  23. claude plugin install apple-mail@apple-mail-mcp
  24. ```
  25. Then restart Claude Code.
  26. ### Other Install Methods
  27. <details>
  28. <summary><strong>uvx (zero install, MCP server only)</strong></summary>
  29. ```bash
  30. claude mcp add apple-mail -- uvx mcp-apple-mail
  31. ```
  32. Or for Claude Desktop (`~/Library/Application Support/Claude/claude_desktop_config.json`):
  33. ```json
  34. {
  35. "mcpServers": {
  36. "apple-mail": {
  37. "command": "uvx",
  38. "args": ["mcp-apple-mail"]
  39. }
  40. }
  41. }
  42. ```
  43. </details>
  44. <details>
  45. <summary><strong>pip install (MCP server only)</strong></summary>
  46. ```bash
  47. pip install mcp-apple-mail
  48. claude mcp add apple-mail -- mcp-apple-mail
  49. ```
  50. </details>
  51. <details>
  52. <summary><strong>npx skills (skill only, for Claude Code, Codex, Cursor and other agents)</strong></summary>
  53. Installs the Email Management Expert skill via the open [skills CLI](https://skills.sh). The skill does not include the MCP server, so install that too (e.g. with uvx above):
  54. ```bash
  55. npx skills add patrickfreyer/apple-mail-mcp
  56. claude mcp add apple-mail -- uvx mcp-apple-mail
  57. ```
  58. Add `-g` to install the skill globally, or `-a <agent>` to target a specific agent.
  59. </details>
  60. <details>
  61. <summary><strong>Claude Desktop MCPB</strong></summary>
  62. 1. Download the latest `apple-mail-mcp-vX.Y.Z.mcpb` from [Releases](https://github.com/patrickfreyer/apple-mail-mcp/releases)
  63. 2. Open Claude Desktop → Settings → Developer → MCP Servers → Install from file
  64. 3. Select the `.mcpb` file and grant Mail.app permissions
  65. </details>
  66. <details>
  67. <summary><strong>Manual setup</strong></summary>
  68. ```bash
  69. git clone https://github.com/patrickfreyer/apple-mail-mcp.git
  70. cd apple-mail-mcp/plugin
  71. python3 -m venv venv
  72. venv/bin/pip install -r requirements.txt
  73. claude mcp add apple-mail -- /bin/bash $(pwd)/start_mcp.sh
  74. ```
  75. </details>
  76. ## Tools (28)
  77. ### Reading & Search
  78. | Tool | Description |
  79. |------|-------------|
  80. | `get_inbox_overview` | Dashboard with unread counts, folders, and recent emails |
  81. | `list_inbox_emails` | List emails with account/read-status filtering and optional content preview |
  82. | `get_mailbox_unread_counts` | Unread counts per mailbox or per-account summary |
  83. | `list_accounts` | List all configured Mail accounts |
  84. | `list_account_addresses` | Email addresses configured for each account |
  85. | `search_emails` | Unified search — subject, sender, body text, dates, attachments, flag status/color, cross-account |
  86. | `read_email` | Read one message by numeric id — headers, capped plain-text body and attachment metadata (text or JSON) |
  87. | `get_email_thread` | Conversation thread view |
  88. | `get_email_source` | Raw RFC 822 source of one message (headers, MIME parts) |
  89. ### Organization
  90. | Tool | Description |
  91. |------|-------------|
  92. | `list_mailboxes` | Folder hierarchy with message counts |
  93. | `create_mailbox` | Create new mailboxes (supports nested paths) |
  94. | `move_email` | Move/archive emails with filters (subject, sender, date, read status, dry-run) |
  95. | `update_email_status` | Mark read/unread, flag/unflag (optional flag color) — by filters or message IDs |
  96. | `manage_trash` | Soft delete, permanent delete, empty trash (with dry-run) |
  97. | `synchronize_account` | Ask Mail.app to check the server for new mail now |
  98. ### Composition
  99. | Tool | Description |
  100. |------|-------------|
  101. | `compose_email` | Send new emails (plain text or HTML body) |
  102. | `reply_to_email` | Reply or reply-all with optional HTML body |
  103. | `forward_email` | Forward with optional message, CC/BCC |
  104. | `manage_drafts` | Create, list, send, and delete drafts |
  105. | `create_rich_email_draft` | Export an unsent HTML `.eml` preview; Mail opens it in a read-only viewer. Use `compose_email(mode="draft")` for a sendable draft |
  106. ### Attachments
  107. | Tool | Description |
  108. |------|-------------|
  109. | `list_email_attachments` | List attachments with names and sizes |
  110. | `save_email_attachment` | Save attachments to disk |
  111. ### Smart Inbox
  112. | Tool | Description |
  113. |------|-------------|
  114. | `get_awaiting_reply` | Find sent emails that haven't received a reply |
  115. | `get_needs_response` | Identify emails that likely need your response |
  116. | `get_top_senders` | Analyse most frequent senders by count or domain |
  117. ### Analytics & Export
  118. | Tool | Description |
  119. |------|-------------|
  120. | `get_statistics` | Email analytics (volume, top senders, read ratios) |
  121. | `export_emails` | Export single emails or mailboxes to TXT/HTML |
  122. | `inbox_dashboard` | Interactive UI dashboard (requires mcp-ui-server) |
  123. ## Configuration
  124. ### Read-Only Mode
  125. Pass `--read-only` to block delivery. Nothing leaves the machine: `compose_email` and `reply_to_email` refuse `mode="send"`, `manage_drafts` refuses `action="send"`, and `forward_email` is removed entirely because it has no non-sending mode.
  126. The composing tools stay registered so that `mode="draft"` and `mode="open"` keep working. Those never deliver anything, and they are the only place in the compose surface that supports `attachments` — `manage_drafts` and `create_rich_email_draft` cannot attach files.
  127. ```json
  128. {
  129. "mcpServers": {
  130. "apple-mail": {
  131. "command": "/path/to/venv/bin/python3",
  132. "args": ["/path/to/apple_mail_mcp.py", "--read-only"]
  133. }
  134. }
  135. }
  136. ```
  137. ### User Preferences (Optional)
  138. Set the `USER_EMAIL_PREFERENCES` environment variable to give the assistant context about your workflow:
  139. ```json
  140. {
  141. "mcpServers": {
  142. "apple-mail": {
  143. "command": "/path/to/venv/bin/python3",
  144. "args": ["/path/to/apple_mail_mcp.py"],
  145. "env": {
  146. "USER_EMAIL_PREFERENCES": "Default to BCG account, show max 50 emails, prefer Archive and Projects folders"
  147. }
  148. }
  149. }
  150. }
  151. ```
  152. For `.mcpb` installs, configure this in Claude Desktop under **Developer > MCP Servers > Apple Mail MCP**.
  153. ### Safety Limits
  154. Batch operations have conservative defaults to prevent accidental bulk actions:
  155. | Operation | Default Limit |
  156. |-----------|---------------|
  157. | `update_email_status` | 10 emails |
  158. | `manage_trash` | 5 emails |
  159. | `move_email` | 1 email |
  160. Override via function parameters when needed.
  161. ### File Access
  162. By default the server can write and attach files anywhere your user account can, except a hardened denylist of locations an attacker could use for code execution or credential theft. (Attachment bytes come from whoever emailed you, and a prompt-injected email can steer tool arguments.)
  163. **Writes** (`save_email_attachment`, `export_emails`, `create_rich_email_draft`'s `output_path`) are refused for:
  164. - any dotfile or dot-folder directly in your home folder: shell startup files (`~/.zshrc`, `~/.zshenv`, `~/.zprofile`, `~/.zlogin`, `~/.bashrc`, `~/.bash_profile`, `~/.profile`), `~/.ssh`, `~/.gnupg`, `~/.aws`, `~/.config` (incl. `~/.config/git`), `~/.gitconfig`, `~/.netrc`, `~/.envrc`, `~/.local/bin`, ...
  165. - `.git/hooks`, `.git/config` and `.envrc` in any folder
  166. - autostart, persistence and app-config folders: `~/Library/LaunchAgents`, `~/Library/LaunchDaemons`, `/Library/LaunchAgents`, `/Library/LaunchDaemons`, `~/Library/Application Support` (incl. `com.apple.backgroundtaskmanagementagent`), `~/Library/Application Scripts`, `~/Library/Preferences`, `~/Library/Keychains`, `~/Library/Mail`, `~/Library/Containers`, ...
  167. - folders on `PATH`: `~/bin`, `/usr/local/bin`, `/opt/homebrew/bin`, and `/etc`
  168. **Attachments** (`compose_email`, `reply_to_email`, ...) may be any readable file except secrets: `~/.ssh`, `~/.gnupg`, `~/.aws`, `~/.netrc`, `~/.git-credentials`, `~/.config/gh`, `.env` files, `~/Library/Keychains`, and browser profiles and cookie stores (Safari, Chrome, Firefox, Edge, Brave, Arc, ...).
  169. Paths are resolved (`~`, `..`, symlinks) before checking, and matching is case-insensitive like APFS.
  170. **Restricting further (opt-in).** To confine writes or attachments to specific folders, list them (colon-separated) in the server's `env`, or pass `--write-dir` / `--attach-dir` (repeatable) as arguments. Once set, only those folders are allowed for that side, and the denylist still applies inside them. The tool's own cache (`~/Library/Caches/apple-mail-mcp`, the default rich-draft location) stays writable.
  171. ```json
  172. "env": {
  173. "APPLE_MAIL_MCP_WRITE_DIRS": "~/Downloads:~/Documents/mail-exports",
  174. "APPLE_MAIL_MCP_ATTACH_DIRS": "~/Documents:~/Desktop"
  175. }
  176. ```
  177. ## Usage Examples
  178. ```
  179. Show me an overview of my inbox
  180. Search for emails about "project update" in my Gmail
  181. Reply to the email about "Domain name" with "Thanks for the update!"
  182. Move emails with "invoice" in the subject to my Archive folder
  183. Show me email statistics for the last 30 days
  184. Create a rich HTML draft for a weekly update and open it in Mail
  185. ```
  186. ### Rich HTML Drafts
  187. Use `create_rich_email_draft` when you need a visually formatted email, newsletter, or leadership update.
  188. - It generates an unsent `.eml` file with multipart plain-text + HTML bodies
  189. - It can open the draft directly in Mail for editing
  190. - It can optionally ask Mail to save the opened compose window into Drafts
  191. - It accepts partial details, so you can start with just an account and subject and fill in the rest later
  192. This is more reliable than injecting raw HTML into AppleScript `content`, which Mail often stores as literal markup.
  193. ## Email Management Skill
  194. A companion [Claude Code Skill](plugin/skills/email-management/) is included that teaches Claude expert email workflows (Inbox Zero, daily triage, folder organization). When installed as a plugin, the skill is loaded automatically. For standalone MCP installs, add it with `npx skills add patrickfreyer/apple-mail-mcp` or copy it manually:
  195. ```bash
  196. cp -r plugin/skills/email-management ~/.claude/skills/email-management
  197. ```
  198. ## Requirements
  199. - macOS with Apple Mail configured
  200. - Python 3.10+ and [uv](https://docs.astral.sh/uv/) for the plugin / uvx installs
  201. - `fastmcp` (+ optional `mcp-ui-server` for dashboard)
  202. - Claude Desktop or any MCP-compatible client
  203. - Mail.app permissions: Automation + Mail Data Access (grant in **System Settings > Privacy & Security > Automation**)
  204. ## Troubleshooting
  205. | Issue | Fix |
  206. |-------|-----|
  207. | Mail.app not responding | Ensure Mail.app is running; check Automation permissions in System Settings |
  208. | Slow searches | Set `include_content: false` and lower `max_results` |
  209. | Mailbox not found | Use exact folder names; nested folders use `/` separator (e.g., `Projects/Alpha`) |
  210. | Permission errors | Grant access in **System Settings > Privacy & Security > Automation** |
  211. | Rich draft shows raw HTML | Use `create_rich_email_draft` instead of pasting HTML into `manage_drafts` or AppleScript `content` |
  212. ## Project Structure
  213. ```
  214. apple-mail-mcp/
  215. ├── .claude-plugin/
  216. │ └── marketplace.json # Marketplace manifest (for plugin distribution)
  217. ├── plugin/ # Claude Code plugin
  218. │ ├── .claude-plugin/
  219. │ │ └── plugin.json # Plugin manifest
  220. │ ├── skills/ # Email Management Expert skill (also invocable as /email-management)
  221. │ ├── apple_mail_mcp/ # Python MCP server package (28 tools)
  222. │ ├── apple_mail_mcp.py # Entry point
  223. │ ├── start_mcp.sh # Startup wrapper for the .mcpb bundle and local clones (auto-creates venv)
  224. │ └── requirements.txt
  225. ├── apple-mail-mcpb/ # MCPB build files (Claude Desktop)
  226. ├── LICENSE
  227. └── README.md
  228. ```
  229. ## Contributing
  230. 1. Fork the repository
  231. 2. Create a feature branch (`git checkout -b feature/my-feature`)
  232. 3. Commit and push
  233. 4. Open a Pull Request
  234. ## Releasing
  235. Follow these steps when cutting a new release to keep all version strings in sync:
  236. 1. Bump `__version__` in `plugin/apple_mail_mcp/__init__.py` to the new version.
  237. 2. Update `apple-mail-mcpb/manifest.json` (`"version"` field) to match.
  238. 3. Update `pyproject.toml` (`version = ...` under `[project]`) to match.
  239. 4. Update both version fields in `server.json` (`"version"` and `"packages"[0]["version"]`) to match.
  240. 5. Run `python3 scripts/check_versions.py` — it must print **OK** before you proceed.
  241. 6. Commit, tag, and push: `git tag vX.Y.Z && git push origin vX.Y.Z`.
  242. 7. Create a GitHub release from the tag.
  243. 8. Build and publish to PyPI: `python -m build && twine upload dist/*` (requires PyPI credentials).
  244. > The test suite also enforces version consistency (`tests/test_version_consistency.py`), so any CI run on a branch with mismatched versions will fail fast.
  245. ## Privacy Policy
  246. The server runs entirely on your Mac, makes no network requests of its own and collects nothing. It reads Mail.app data only when a tool asks, returns it to your MCP client, and sends email only when you ask a sending tool to. Installing through the plugin downloads the pinned `mcp-apple-mail` package from PyPI with `uvx`. Full policy: [PRIVACY.md](PRIVACY.md).
  247. ## License
  248. MIT -- see [LICENSE](LICENSE).
  249. ## Links
  250. - [Changelog](CHANGELOG.md)
  251. - [Issues](https://github.com/patrickfreyer/apple-mail-mcp/issues)
  252. - [Discussions](https://github.com/patrickfreyer/apple-mail-mcp/discussions)
  253. - [FastMCP](https://github.com/jlowin/fastmcp)
  254. - [Model Context Protocol](https://modelcontextprotocol.io)

Ratings and comments

Sign in to rate this skill.

Sign in

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