apple-mail-mcp
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Badge for your README
Markdown
[](/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
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
- {
- "name": "apple-mail-mcp",
- "owner": {
- "name": "Patrick Freyer",
- "email": "freyer.patrick@bcg.com"
- },
- "metadata": {
- "description": "Apple Mail MCP — natural language email management for Claude Code",
- "version": "1.0.0"
- },
- "plugins": [
- {
- "name": "apple-mail",
- "source": "./plugin",
- "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",
- "version": "3.4.0",
- "author": {
- "name": "Patrick Freyer"
- }
- }
- ]
- }
README.md · README · 341 lines
- # Apple Mail MCP Server
- <!-- mcp-name: io.github.patrickfreyer/apple-mail -->
- [](https://opensource.org/licenses/MIT)
- [](https://pypi.org/project/mcp-apple-mail/)
- [](https://www.python.org/downloads/)
- [](https://modelcontextprotocol.io)
- [](https://github.com/patrickfreyer/apple-mail-mcp/stargazers)
- ## Star History
- <a href="https://star-history.com/#patrickfreyer/apple-mail-mcp&Date">
- <picture>
- <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/svg?repos=patrickfreyer/apple-mail-mcp&type=Date&theme=dark" />
- <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/svg?repos=patrickfreyer/apple-mail-mcp&type=Date" />
- <img alt="Star History Chart" src="https://api.star-history.com/svg?repos=patrickfreyer/apple-mail-mcp&type=Date" />
- </picture>
- </a>
- 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).
- ## Quick Install
- **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:
- ```bash
- 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>
- ```bash
- claude mcp add apple-mail -- uvx mcp-apple-mail
- ```
- Or for Claude Desktop (`~/Library/Application Support/Claude/claude_desktop_config.json`):
- ```json
- {
- "mcpServers": {
- "apple-mail": {
- "command": "uvx",
- "args": ["mcp-apple-mail"]
- }
- }
- }
- ```
- </details>
- <details>
- <summary><strong>pip install (MCP server only)</strong></summary>
- ```bash
- 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):
- ```bash
- 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>
- ```bash
- 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>
- ## Tools (28)
- ### Reading & Search
- | Tool | Description |
- |------|-------------|
- | `get_inbox_overview` | Dashboard with unread counts, folders, and recent emails |
- | `list_inbox_emails` | List emails with account/read-status filtering and optional content preview |
- | `get_mailbox_unread_counts` | Unread counts per mailbox or per-account summary |
- | `list_accounts` | List all configured Mail accounts |
- | `list_account_addresses` | Email addresses configured for each account |
- | `search_emails` | Unified search — subject, sender, body text, dates, attachments, flag status/color, cross-account |
- | `read_email` | Read one message by numeric id — headers, capped plain-text body and attachment metadata (text or JSON) |
- | `get_email_thread` | Conversation thread view |
- | `get_email_source` | Raw RFC 822 source of one message (headers, MIME parts) |
- ### Organization
- | Tool | Description |
- |------|-------------|
- | `list_mailboxes` | Folder hierarchy with message counts |
- | `create_mailbox` | Create new mailboxes (supports nested paths) |
- | `move_email` | Move/archive emails with filters (subject, sender, date, read status, dry-run) |
- | `update_email_status` | Mark read/unread, flag/unflag (optional flag color) — by filters or message IDs |
- | `manage_trash` | Soft delete, permanent delete, empty trash (with dry-run) |
- | `synchronize_account` | Ask Mail.app to check the server for new mail now |
- ### Composition
- | Tool | Description |
- |------|-------------|
- | `compose_email` | Send new emails (plain text or HTML body) |
- | `reply_to_email` | Reply or reply-all with optional HTML body |
- | `forward_email` | Forward with optional message, CC/BCC |
- | `manage_drafts` | Create, list, send, and delete drafts |
- | `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 |
- ### Attachments
- | Tool | Description |
- |------|-------------|
- | `list_email_attachments` | List attachments with names and sizes |
- | `save_email_attachment` | Save attachments to disk |
- ### Smart Inbox
- | Tool | Description |
- |------|-------------|
- | `get_awaiting_reply` | Find sent emails that haven't received a reply |
- | `get_needs_response` | Identify emails that likely need your response |
- | `get_top_senders` | Analyse most frequent senders by count or domain |
- ### Analytics & Export
- | Tool | Description |
- |------|-------------|
- | `get_statistics` | Email analytics (volume, top senders, read ratios) |
- | `export_emails` | Export single emails or mailboxes to TXT/HTML |
- | `inbox_dashboard` | Interactive UI dashboard (requires mcp-ui-server) |
- ## Configuration
- ### Read-Only Mode
- 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.
- 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.
- ```json
- {
- "mcpServers": {
- "apple-mail": {
- "command": "/path/to/venv/bin/python3",
- "args": ["/path/to/apple_mail_mcp.py", "--read-only"]
- }
- }
- }
- ```
- ### User Preferences (Optional)
- Set the `USER_EMAIL_PREFERENCES` environment variable to give the assistant context about your workflow:
- ```json
- {
- "mcpServers": {
- "apple-mail": {
- "command": "/path/to/venv/bin/python3",
- "args": ["/path/to/apple_mail_mcp.py"],
- "env": {
- "USER_EMAIL_PREFERENCES": "Default to BCG account, show max 50 emails, prefer Archive and Projects folders"
- }
- }
- }
- }
- ```
- For `.mcpb` installs, configure this in Claude Desktop under **Developer > MCP Servers > Apple Mail MCP**.
- ### Safety Limits
- Batch operations have conservative defaults to prevent accidental bulk actions:
- | Operation | Default Limit |
- |-----------|---------------|
- | `update_email_status` | 10 emails |
- | `manage_trash` | 5 emails |
- | `move_email` | 1 email |
- Override via function parameters when needed.
- ### File Access
- 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.)
- **Writes** (`save_email_attachment`, `export_emails`, `create_rich_email_draft`'s `output_path`) are refused for:
- - 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`, ...
- - `.git/hooks`, `.git/config` and `.envrc` in any folder
- - 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`, ...
- - folders on `PATH`: `~/bin`, `/usr/local/bin`, `/opt/homebrew/bin`, and `/etc`
- **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, ...).
- Paths are resolved (`~`, `..`, symlinks) before checking, and matching is case-insensitive like APFS.
- **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.
- ```json
- "env": {
- "APPLE_MAIL_MCP_WRITE_DIRS": "~/Downloads:~/Documents/mail-exports",
- "APPLE_MAIL_MCP_ATTACH_DIRS": "~/Documents:~/Desktop"
- }
- ```
- ## Usage Examples
- ```
- Show me an overview of my inbox
- Search for emails about "project update" in my Gmail
- Reply to the email about "Domain name" with "Thanks for the update!"
- Move emails with "invoice" in the subject to my Archive folder
- Show me email statistics for the last 30 days
- Create a rich HTML draft for a weekly update and open it in Mail
- ```
- ### Rich HTML Drafts
- Use `create_rich_email_draft` when you need a visually formatted email, newsletter, or leadership update.
- - It generates an unsent `.eml` file with multipart plain-text + HTML bodies
- - It can open the draft directly in Mail for editing
- - It can optionally ask Mail to save the opened compose window into Drafts
- - It accepts partial details, so you can start with just an account and subject and fill in the rest later
- This is more reliable than injecting raw HTML into AppleScript `content`, which Mail often stores as literal markup.
- ## Email Management Skill
- 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:
- ```bash
- cp -r plugin/skills/email-management ~/.claude/skills/email-management
- ```
- ## Requirements
- - macOS with Apple Mail configured
- - Python 3.10+ and [uv](https://docs.astral.sh/uv/) for the plugin / uvx installs
- - `fastmcp` (+ optional `mcp-ui-server` for dashboard)
- - Claude Desktop or any MCP-compatible client
- - Mail.app permissions: Automation + Mail Data Access (grant in **System Settings > Privacy & Security > Automation**)
- ## Troubleshooting
- | Issue | Fix |
- |-------|-----|
- | Mail.app not responding | Ensure Mail.app is running; check Automation permissions in System Settings |
- | Slow searches | Set `include_content: false` and lower `max_results` |
- | Mailbox not found | Use exact folder names; nested folders use `/` separator (e.g., `Projects/Alpha`) |
- | Permission errors | Grant access in **System Settings > Privacy & Security > Automation** |
- | Rich draft shows raw HTML | Use `create_rich_email_draft` instead of pasting HTML into `manage_drafts` or AppleScript `content` |
- ## Project Structure
- ```
- apple-mail-mcp/
- ├── .claude-plugin/
- │ └── marketplace.json # Marketplace manifest (for plugin distribution)
- ├── plugin/ # Claude Code plugin
- │ ├── .claude-plugin/
- │ │ └── plugin.json # Plugin manifest
- │ ├── skills/ # Email Management Expert skill (also invocable as /email-management)
- │ ├── apple_mail_mcp/ # Python MCP server package (28 tools)
- │ ├── apple_mail_mcp.py # Entry point
- │ ├── start_mcp.sh # Startup wrapper for the .mcpb bundle and local clones (auto-creates venv)
- │ └── requirements.txt
- ├── apple-mail-mcpb/ # MCPB build files (Claude Desktop)
- ├── LICENSE
- └── README.md
- ```
- ## Contributing
- 1. Fork the repository
- 2. Create a feature branch (`git checkout -b feature/my-feature`)
- 3. Commit and push
- 4. Open a Pull Request
- ## Releasing
- Follow these steps when cutting a new release to keep all version strings in sync:
- 1. Bump `__version__` in `plugin/apple_mail_mcp/__init__.py` to the new version.
- 2. Update `apple-mail-mcpb/manifest.json` (`"version"` field) to match.
- 3. Update `pyproject.toml` (`version = ...` under `[project]`) to match.
- 4. Update both version fields in `server.json` (`"version"` and `"packages"[0]["version"]`) to match.
- 5. Run `python3 scripts/check_versions.py` — it must print **OK** before you proceed.
- 6. Commit, tag, and push: `git tag vX.Y.Z && git push origin vX.Y.Z`.
- 7. Create a GitHub release from the tag.
- 8. Build and publish to PyPI: `python -m build && twine upload dist/*` (requires PyPI credentials).
- > 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.
- ## Privacy Policy
- 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).
- ## License
- MIT -- see [LICENSE](LICENSE).
- ## Links
- - [Changelog](CHANGELOG.md)
- - [Issues](https://github.com/patrickfreyer/apple-mail-mcp/issues)
- - [Discussions](https://github.com/patrickfreyer/apple-mail-mcp/discussions)
- - [FastMCP](https://github.com/jlowin/fastmcp)
- - [Model Context Protocol](https://modelcontextprotocol.io)
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.