{"id":47067136,"url":"https://github.com/patrickfreyer/apple-mail-mcp","last_synced_at":"2026-04-02T16:08:29.296Z","repository":{"id":318750147,"uuid":"1076389075","full_name":"patrickfreyer/apple-mail-mcp","owner":"patrickfreyer","description":"MCP server giving AI assistants full access to Apple Mail - read, search, compose, organize \u0026 analyze emails via natural language","archived":false,"fork":false,"pushed_at":"2026-03-10T19:57:23.000Z","size":270,"stargazers_count":44,"open_issues_count":0,"forks_count":18,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-03-10T22:42:29.914Z","etag":null,"topics":["ai","apple-mail","applescript","automation","claude","email","fastmcp","macos","mcp","mcp-server"],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/patrickfreyer.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-10-14T19:40:48.000Z","updated_at":"2026-03-10T20:24:42.000Z","dependencies_parsed_at":"2025-10-15T01:51:29.604Z","dependency_job_id":"8809ff3c-2d86-45dd-8e26-0777bde7cb84","html_url":"https://github.com/patrickfreyer/apple-mail-mcp","commit_stats":null,"previous_names":["patrickfreyer/apple-mail-mcp"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/patrickfreyer/apple-mail-mcp","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/patrickfreyer%2Fapple-mail-mcp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/patrickfreyer%2Fapple-mail-mcp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/patrickfreyer%2Fapple-mail-mcp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/patrickfreyer%2Fapple-mail-mcp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/patrickfreyer","download_url":"https://codeload.github.com/patrickfreyer/apple-mail-mcp/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/patrickfreyer%2Fapple-mail-mcp/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30416310,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-12T04:41:02.746Z","status":"ssl_error","status_checked_at":"2026-03-12T04:40:12.571Z","response_time":114,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai","apple-mail","applescript","automation","claude","email","fastmcp","macos","mcp","mcp-server"],"created_at":"2026-03-12T05:08:47.050Z","updated_at":"2026-04-02T16:08:29.284Z","avatar_url":"https://github.com/patrickfreyer.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Apple Mail MCP Server\n\n\u003c!-- mcp-name: io.github.patrickfreyer/apple-mail --\u003e\n\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![PyPI](https://img.shields.io/pypi/v/mcp-apple-mail)](https://pypi.org/project/mcp-apple-mail/)\n[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)\n[![MCP](https://img.shields.io/badge/MCP-Compatible-green.svg)](https://modelcontextprotocol.io)\n[![GitHub stars](https://img.shields.io/github/stars/patrickfreyer/apple-mail-mcp?style=social)](https://github.com/patrickfreyer/apple-mail-mcp/stargazers)\n\n## Star History\n\n\u003ca href=\"https://star-history.com/#patrickfreyer/apple-mail-mcp\u0026Date\"\u003e\n \u003cpicture\u003e\n   \u003csource media=\"(prefers-color-scheme: dark)\" srcset=\"https://api.star-history.com/svg?repos=patrickfreyer/apple-mail-mcp\u0026type=Date\u0026theme=dark\" /\u003e\n   \u003csource media=\"(prefers-color-scheme: light)\" srcset=\"https://api.star-history.com/svg?repos=patrickfreyer/apple-mail-mcp\u0026type=Date\" /\u003e\n   \u003cimg alt=\"Star History Chart\" src=\"https://api.star-history.com/svg?repos=patrickfreyer/apple-mail-mcp\u0026type=Date\" /\u003e\n \u003c/picture\u003e\n\u003c/a\u003e\n\nAn 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).\n\n## Quick Install\n\n**Prerequisites:** macOS with Apple Mail configured, Python 3.10+\n\n### Claude Code Plugin (Recommended)\n\nTwo commands — gets you the MCP server, `/email-management` slash command, and the Email Management Expert skill:\n\n```bash\nclaude plugin marketplace add patrickfreyer/apple-mail-mcp\nclaude plugin install apple-mail@apple-mail-mcp\n```\n\nThen restart Claude Code.\n\n### Other Install Methods\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003euvx (zero install, MCP server only)\u003c/strong\u003e\u003c/summary\u003e\n\n```bash\nclaude mcp add apple-mail -- uvx mcp-apple-mail\n```\n\nOr for Claude Desktop (`~/Library/Application Support/Claude/claude_desktop_config.json`):\n\n```json\n{\n  \"mcpServers\": {\n    \"apple-mail\": {\n      \"command\": \"uvx\",\n      \"args\": [\"mcp-apple-mail\"]\n    }\n  }\n}\n```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003epip install (MCP server only)\u003c/strong\u003e\u003c/summary\u003e\n\n```bash\npip install mcp-apple-mail\nclaude mcp add apple-mail -- mcp-apple-mail\n```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eClaude Desktop MCPB\u003c/strong\u003e\u003c/summary\u003e\n\n1. Download `apple-mail-mcp-v2.2.0.mcpb` from [Releases](https://github.com/patrickfreyer/apple-mail-mcp/releases)\n2. Open Claude Desktop → Settings → Developer → MCP Servers → Install from file\n3. Select the `.mcpb` file and grant Mail.app permissions\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eManual setup\u003c/strong\u003e\u003c/summary\u003e\n\n```bash\ngit clone https://github.com/patrickfreyer/apple-mail-mcp.git\ncd apple-mail-mcp/plugin\npython3 -m venv venv\nvenv/bin/pip install -r requirements.txt\n\nclaude mcp add apple-mail -- /bin/bash $(pwd)/start_mcp.sh\n```\n\n\u003c/details\u003e\n\n## Tools (22)\n\n### Reading \u0026 Search\n| Tool | Description |\n|------|-------------|\n| `get_inbox_overview` | Dashboard with unread counts, folders, and recent emails |\n| `list_inbox_emails` | List emails with account/read-status filtering and optional content preview |\n| `get_mailbox_unread_counts` | Unread counts per mailbox or per-account summary |\n| `list_accounts` | List all configured Mail accounts |\n| `search_emails` | Unified search — subject, sender, body text, dates, attachments, cross-account |\n| `get_email_thread` | Conversation thread view |\n\n### Organization\n| Tool | Description |\n|------|-------------|\n| `list_mailboxes` | Folder hierarchy with message counts |\n| `create_mailbox` | Create new mailboxes (supports nested paths) |\n| `move_email` | Move/archive emails with filters (subject, sender, date, read status, dry-run) |\n| `update_email_status` | Mark read/unread, flag/unflag — by filters or message IDs |\n| `manage_trash` | Soft delete, permanent delete, empty trash (with dry-run) |\n\n### Composition\n| Tool | Description |\n|------|-------------|\n| `compose_email` | Send new emails (plain text or HTML body) |\n| `reply_to_email` | Reply or reply-all with optional HTML body |\n| `forward_email` | Forward with optional message, CC/BCC |\n| `manage_drafts` | Create, list, send, and delete drafts |\n| `create_rich_email_draft` | Build a rich HTML `.eml` draft, open it in Mail, and optionally save it to Drafts |\n\n### Attachments\n| Tool | Description |\n|------|-------------|\n| `list_email_attachments` | List attachments with names and sizes |\n| `save_email_attachment` | Save attachments to disk |\n\n### Smart Inbox\n| Tool | Description |\n|------|-------------|\n| `get_awaiting_reply` | Find sent emails that haven't received a reply |\n| `get_needs_response` | Identify emails that likely need your response |\n| `get_top_senders` | Analyse most frequent senders by count or domain |\n\n### Analytics \u0026 Export\n| Tool | Description |\n|------|-------------|\n| `get_statistics` | Email analytics (volume, top senders, read ratios) |\n| `export_emails` | Export single emails or mailboxes to TXT/HTML |\n| `inbox_dashboard` | Interactive UI dashboard (requires mcp-ui-server) |\n\n## Configuration\n\n### Read-Only Mode\n\nPass `--read-only` to disable tools that send email (`compose_email`, `reply_to_email`, `forward_email`). Draft management remains available (list, create, delete) but sending a draft via `manage_drafts` is blocked.\n\n```json\n{\n  \"mcpServers\": {\n    \"apple-mail\": {\n      \"command\": \"/path/to/venv/bin/python3\",\n      \"args\": [\"/path/to/apple_mail_mcp.py\", \"--read-only\"]\n    }\n  }\n}\n```\n\n### User Preferences (Optional)\n\nSet the `USER_EMAIL_PREFERENCES` environment variable to give the assistant context about your workflow:\n\n```json\n{\n  \"mcpServers\": {\n    \"apple-mail\": {\n      \"command\": \"/path/to/venv/bin/python3\",\n      \"args\": [\"/path/to/apple_mail_mcp.py\"],\n      \"env\": {\n        \"USER_EMAIL_PREFERENCES\": \"Default to BCG account, show max 50 emails, prefer Archive and Projects folders\"\n      }\n    }\n  }\n}\n```\n\nFor `.mcpb` installs, configure this in Claude Desktop under **Developer \u003e MCP Servers \u003e Apple Mail MCP**.\n\n### Safety Limits\n\nBatch operations have conservative defaults to prevent accidental bulk actions:\n\n| Operation | Default Limit |\n|-----------|---------------|\n| `update_email_status` | 10 emails |\n| `manage_trash` | 5 emails |\n| `move_email` | 1 email |\n\nOverride via function parameters when needed.\n\n## Usage Examples\n\n```\nShow me an overview of my inbox\nSearch for emails about \"project update\" in my Gmail\nReply to the email about \"Domain name\" with \"Thanks for the update!\"\nMove emails with \"invoice\" in the subject to my Archive folder\nShow me email statistics for the last 30 days\nCreate a rich HTML draft for a weekly update and open it in Mail\n```\n\n### Rich HTML Drafts\n\nUse `create_rich_email_draft` when you need a visually formatted email, newsletter, or leadership update.\n\n- It generates an unsent `.eml` file with multipart plain-text + HTML bodies\n- It can open the draft directly in Mail for editing\n- It can optionally ask Mail to save the opened compose window into Drafts\n- It accepts partial details, so you can start with just an account and subject and fill in the rest later\n\nThis is more reliable than injecting raw HTML into AppleScript `content`, which Mail often stores as literal markup.\n\n## Email Management Skill\n\nA 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, copy it manually:\n\n```bash\ncp -r plugin/skills/email-management ~/.claude/skills/email-management\n```\n\n## Requirements\n\n- macOS with Apple Mail configured\n- Python 3.7+\n- `fastmcp` (+ optional `mcp-ui-server` for dashboard)\n- Claude Desktop or any MCP-compatible client\n- Mail.app permissions: Automation + Mail Data Access (grant in **System Settings \u003e Privacy \u0026 Security \u003e Automation**)\n\n## Troubleshooting\n\n| Issue | Fix |\n|-------|-----|\n| Mail.app not responding | Ensure Mail.app is running; check Automation permissions in System Settings |\n| Slow searches | Set `include_content: false` and lower `max_results` |\n| Mailbox not found | Use exact folder names; nested folders use `/` separator (e.g., `Projects/Alpha`) |\n| Permission errors | Grant access in **System Settings \u003e Privacy \u0026 Security \u003e Automation** |\n| Rich draft shows raw HTML | Use `create_rich_email_draft` instead of pasting HTML into `manage_drafts` or AppleScript `content` |\n\n## Project Structure\n\n```\napple-mail-mcp/\n├── .claude-plugin/\n│   └── marketplace.json       # Marketplace manifest (for plugin distribution)\n├── plugin/                    # Claude Code plugin\n│   ├── .claude-plugin/\n│   │   └── plugin.json        # Plugin manifest\n│   ├── commands/              # /email-management slash command\n│   ├── skills/                # Email Management Expert skill\n│   ├── apple_mail_mcp/        # Python MCP server package (24 tools)\n│   ├── apple_mail_mcp.py      # Entry point\n│   ├── start_mcp.sh           # Startup wrapper (auto-creates venv)\n│   └── requirements.txt\n├── apple-mail-mcpb/           # MCPB build files (Claude Desktop)\n├── LICENSE\n└── README.md\n```\n\n## Contributing\n\n1. Fork the repository\n2. Create a feature branch (`git checkout -b feature/my-feature`)\n3. Commit and push\n4. Open a Pull Request\n\n## License\n\nMIT -- see [LICENSE](LICENSE).\n\n## Links\n\n- [Changelog](CHANGELOG.md)\n- [Issues](https://github.com/patrickfreyer/apple-mail-mcp/issues)\n- [Discussions](https://github.com/patrickfreyer/apple-mail-mcp/discussions)\n- [FastMCP](https://github.com/jlowin/fastmcp)\n- [Model Context Protocol](https://modelcontextprotocol.io)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpatrickfreyer%2Fapple-mail-mcp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpatrickfreyer%2Fapple-mail-mcp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpatrickfreyer%2Fapple-mail-mcp/lists"}