{"id":45645851,"url":"https://github.com/imdinu/apple-mail-mcp","last_synced_at":"2026-05-10T17:20:42.901Z","repository":{"id":334923353,"uuid":"1142896113","full_name":"imdinu/apple-mail-mcp","owner":"imdinu","description":"Apple Mail MCP server with full-text email search — the only one that works reliably on large mailboxes. 6 tools for Claude Desktop \u0026 Claude Code.","archived":false,"fork":false,"pushed_at":"2026-04-01T14:24:04.000Z","size":2138,"stargazers_count":10,"open_issues_count":21,"forks_count":6,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-04-03T06:47:50.794Z","etag":null,"topics":["apple-mail","automation","claude","email","fts5","jxa","macos","mcp","mcp-server","model-context-protocol"],"latest_commit_sha":null,"homepage":"https://imdinu.github.io/apple-mail-mcp/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/imdinu.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","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":"2026-01-27T01:12:53.000Z","updated_at":"2026-04-01T14:23:57.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/imdinu/apple-mail-mcp","commit_stats":null,"previous_names":["imdinu/jxa-mail-mcp","imdinu/apple-mail-mcp"],"tags_count":14,"template":false,"template_full_name":null,"purl":"pkg:github/imdinu/apple-mail-mcp","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/imdinu%2Fapple-mail-mcp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/imdinu%2Fapple-mail-mcp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/imdinu%2Fapple-mail-mcp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/imdinu%2Fapple-mail-mcp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/imdinu","download_url":"https://codeload.github.com/imdinu/apple-mail-mcp/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/imdinu%2Fapple-mail-mcp/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31442926,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-05T15:22:31.103Z","status":"ssl_error","status_checked_at":"2026-04-05T15:22:00.205Z","response_time":75,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5: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":["apple-mail","automation","claude","email","fts5","jxa","macos","mcp","mcp-server","model-context-protocol"],"created_at":"2026-02-24T04:00:39.910Z","updated_at":"2026-05-10T17:20:42.896Z","avatar_url":"https://github.com/imdinu.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Apple Mail MCP\n\n\u003c!-- mcp-name: io.github.imdinu/apple-mail-mcp --\u003e\n\n[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)\n[![License: GPL v3](https://img.shields.io/badge/License-GPLv3-blue.svg)](https://www.gnu.org/licenses/gpl-3.0)\n[![macOS](https://img.shields.io/badge/platform-macOS-lightgrey.svg)](https://www.apple.com/macos/)\n[![MCP](https://img.shields.io/badge/MCP-compatible-green.svg)](https://modelcontextprotocol.io/)\n[![Code style: ruff](https://img.shields.io/badge/code%20style-ruff-000000.svg)](https://github.com/astral-sh/ruff)\n[![CI](https://github.com/imdinu/apple-mail-mcp/actions/workflows/lint.yml/badge.svg)](https://github.com/imdinu/apple-mail-mcp/actions/workflows/lint.yml)\n\nThe only Apple Mail MCP server with **full-text email search**. Reliable on large mailboxes where other servers timeout — with 8 tools for reading, searching, and extracting email content.\n\n**[Read the docs](https://imdinu.github.io/apple-mail-mcp/)** for the full guide.\n\n## Quick Start\n\n```bash\npipx install apple-mail-mcp\n```\n\nAdd to your MCP client:\n\n```json\n{\n  \"mcpServers\": {\n    \"mail\": {\n      \"command\": \"apple-mail-mcp\"\n    }\n  }\n}\n```\n\n### Build the Search Index (Recommended)\n\n```bash\n# Requires Full Disk Access for Terminal\n# System Settings → Privacy \u0026 Security → Full Disk Access → Add Terminal\n\napple-mail-mcp index --verbose\n```\n\n## Tools\n\n| Tool | Purpose |\n|------|---------|\n| `list_accounts()` | List email accounts |\n| `list_mailboxes(account?)` | List mailboxes |\n| `get_emails(filter?, limit?)` | Get emails — all, unread, flagged, today, last_7_days |\n| `get_email(message_id)` | Get single email with full content + attachments |\n| `search(query, scope?, before?, after?, highlight?)` | Search — all, subject, sender, body, attachments |\n| `get_email_links(message_id)` | Extract links from an email |\n| `get_email_attachment(message_id, filename)` | Extract attachment content |\n| `get_attachment(message_id, filename)` | *Deprecated* — use `get_email_attachment()` |\n\n## Performance\n\nTested against [8 other Apple Mail MCP servers](https://imdinu.github.io/apple-mail-mcp/benchmarks/) on a real **~72K-message** mailbox:\n\n- **Only server with full-coverage body search.** Most competitors don't support body search at all; the one that does (BastianZim) live-scans only the 5000 most recent messages — silent miss on anything older. Our FTS5 index covers the entire mailbox.\n- **~3ms single email fetch** via disk-first `.emlx` reading (no JXA round-trip).\n- **~7ms subject search** via FTS5 — competitive with native Rust on the same operation.\n- **Reliable across all 6 benchmarked operations** on a 72K mailbox; AppleScript-based servers timeout, throw syntax errors, or skip operations they don't support.\n\n![Capability Matrix](docs/benchmark_overview.png)\n\n## Configuration\n\n| Variable | Default | Description |\n|----------|---------|-------------|\n| `APPLE_MAIL_DEFAULT_ACCOUNT` | First account | Default email account |\n| `APPLE_MAIL_DEFAULT_MAILBOX` | `INBOX` | Default mailbox |\n| `APPLE_MAIL_INDEX_PATH` | `~/.apple-mail-mcp/index.db` | Index location |\n| `APPLE_MAIL_INDEX_MAX_EMAILS` | _unset_ | Optional per-mailbox ceiling (default: uncapped) |\n| `APPLE_MAIL_INDEX_EXCLUDE_MAILBOXES` | `Drafts` | Mailboxes to skip in search |\n| `APPLE_MAIL_READ_ONLY` | `false` | Disable write operations |\n\n```json\n{\n  \"mcpServers\": {\n    \"mail\": {\n      \"command\": \"apple-mail-mcp\",\n      \"args\": [\"--watch\"],\n      \"env\": {\n        \"APPLE_MAIL_DEFAULT_ACCOUNT\": \"Work\"\n      }\n    }\n  }\n}\n```\n\n## CLI Usage\n\nAll tools are also available as standalone CLI commands (no MCP server needed):\n\n```bash\napple-mail-mcp search \"quarterly report\" --scope subject\napple-mail-mcp search \"invoice\" --after 2026-01-01 --limit 10\napple-mail-mcp read 12345\napple-mail-mcp emails --filter unread --limit 10\napple-mail-mcp accounts\napple-mail-mcp mailboxes --account Work\napple-mail-mcp extract 12345 invoice.pdf\n```\n\nAll commands output JSON. Generate a [Claude Code skill](https://imdinu.github.io/apple-mail-mcp/configuration/#cli-commands) for CLI-based access:\n\n```bash\napple-mail-mcp integrate claude \u003e ~/.claude/skills/apple-mail.md\n```\n\n## Development\n\n```bash\ngit clone https://github.com/imdinu/apple-mail-mcp\ncd apple-mail-mcp\nuv sync\nuv run ruff check src/\nuv run pytest\n```\n\n## License\n\nGPL-3.0-or-later\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fimdinu%2Fapple-mail-mcp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fimdinu%2Fapple-mail-mcp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fimdinu%2Fapple-mail-mcp/lists"}