# Reported issues for Apple Mail MCP Pod holds 10 of 10 problems reported by people outside the maintainer team. Issues filed by the project's own owners, members and collaborators are excluded entirely — a maintainer's release checklist is not a warning to a prospective user. Back to [Apple Mail MCP](/mcp/apple-mail-mcp). ## Most discussed ### search() cannot distinguish a missing index from a genuine no-match, so an unbuilt index reads as an empty mailbox `search()` cannot distinguish "no index" from "no match", so an unbuilt or stale index looks exactly like a genuinely empty result. On my install that cost roughly four months of silently empty searches, on a mailbox of 18,232 emails that would have matched constantly. Filing this with the backing of the Dex project, where the same problem is tracked as davekilleen/Dex#446. Dave (the maintainer there) asked me to bring it here directly since I have the reproduction. Happy to send a PR if the sh [Read the thread](https://github.com/imdinu/apple-mail-mcp/issues/110) · 2026-08-12 · closed · outside contributor · 2 comments ### PermissionError escapes both no-FDA fallbacks: get_emails() fails outright, and attachment reads report "not found" Running without Full Disk Access — which the docs describe as supported ("The MCP server itself does **not** need Full Disk Access — only the `index` and `rebuild` commands do", `docs/troubleshooting.md`) — two code paths fail in ways that look like different bugs but share one root cause. `PermissionError` subclasses `OSError`, not `FileNotFoundError`. Both sites below have a handler that clearly intends to cover an unreadable Mail store, and `PermissionError` walks straight past it. Happy to [Read the thread](https://github.com/imdinu/apple-mail-mcp/issues/109) · 2026-08-07 · open · external user · 2 comments ### Two concurrent --watch instances (Claude Desktop spawns MCP servers twice) cause write storm, unbounded WAL growth and blocked FTS searches ## Environment - apple-mail-mcp 0.4.2 - macOS 26.5.2 - Claude Desktop as MCP client - Observed on 2026-07-15 ## Summary Claude Desktop structurally spawns **two instances** of every configured MCP server — one for Desktop chats and one for the Claude Code bridge. When both instances run with `serve --watch`, the two watchfiles watchers operate on the same SQLite database (`~/.apple-mail-mcp/index.db`, WAL mode) and get into a sustained write storm. ## Symptoms - Log spam every few seconds: `In [Read the thread](https://github.com/imdinu/apple-mail-mcp/issues/106) · 2026-07-15 · closed · external user · 1 comment ### Feature request: APPLE_MAIL_INDEX_EXCLUDE_ACCOUNTS for account-level index exclusion ## Summary Request a new environment variable `APPLE_MAIL_INDEX_EXCLUDE_ACCOUNTS` (comma-separated, like the existing `APPLE_MAIL_INDEX_EXCLUDE_MAILBOXES`) that excludes entire accounts from the index at build time. ## Motivation `APPLE_MAIL_INDEX_EXCLUDE_MAILBOXES` matches by mailbox name only, with no account-qualified syntax. This works fine for excluding category folders like Drafts (the default), but fails for the common case of wanting to exclude an entire account whose mailboxes have g [Read the thread](https://github.com/imdinu/apple-mail-mcp/issues/90) · 2026-05-22 · closed · external user · 2 comments ### Attachment Download Error Always got error: attachment not found when run with cloude coworker. But can got it when via MCP Inspector. get_email_attachment Request { "message_id": 437629, "filename": "GCEMEARSD0000290714-2.pdf", "account": "info@playlingo.app", "mailbox": "[Gmail]" } Error Error calling tool 'get_email_attachment': Attachment 'GCEMEARSD0000290714-2.pdf' not found in email 437629. [Read the thread](https://github.com/imdinu/apple-mail-mcp/issues/71) · 2026-04-03 · closed · external user · 2 comments ### MCS server is disconnected When claude desktop started i got this notification Image log: 2026-04-03T08:20:33.103Z [mail] [info] Initializing server... { metadata: undefined } 2026-04-03T08:20:33.105Z [mail] [info] Using MCP server command: apple-mail-mcp with args and path: { metadata: { args: [ [length]: 0 ], paths: [ '/usr/local/bin', '/opt/homebrew/bin', '/usr/bi [Read the thread](https://github.com/imdinu/apple-mail-mcp/issues/70) · 2026-04-03 · closed · external user · 0 comments ### get_email type coercion + search mailbox scope + scheduled mode failures ## Bug Report — Three related issues in scheduled/automated mode ### Environment - Version: v0.1.8 - Running via: Claude Cowork scheduled tasks (automated, unattended) --- ### Bug 1: `get_email` — message_id type coercion in scheduled mode When called from a scheduled task, `message_id` is passed as a string instead of an integer. The tool rejects it with a type error, making it impossible to read email bodies in any automated context. **Workaround:** None reliable. Triage falls back to m [Read the thread](https://github.com/imdinu/apple-mail-mcp/issues/67) · 2026-03-27 · closed · external user · 3 comments ### Large mailboxes timeout on startup I have a lot of emails (400,000+). I can build the index, but every time I open Claude, the MCP server takes too long to traverse all the email (needs about 2 minutes) and as a result Claude pops up an error message saying that it cannot connect to the MCP server. It would be great if you can find a way to support large mailboxes. Perhaps the software could do the start-up scan in the background, so that it can still respond to Claude when it tries to connect to the MCP server? Thanks [Read the thread](https://github.com/imdinu/apple-mail-mcp/issues/51) · 2026-03-04 · closed · external user · 3 comments ## Most recent ### get_emails() silently returns [] for Gmail-backed accounts: Envelope Index fast path misses label-based mailbox membership ## Problem On 0.4.0/0.4.1, `get_emails(account, mailbox)` returns an empty list for Gmail-backed accounts even when the mailbox has plenty of mail. No error is raised, so the JXA fallback never runs and the caller gets a silently wrong empty result. ## Repro (real mailbox, macOS 14, Mail V10) `get_emails(account="", mailbox="INBOX")` returned `[]` for an INBOX that AppleScript confirms holds 104 messages. ## Root cause The Strategy-0 fast path assumes mailbox membership is ex [Read the thread](https://github.com/imdinu/apple-mail-mcp/issues/102) · 2026-06-12 · closed · outside contributor · 0 comments ### Alternative install fix for Claude Desktop — cyclopts dependency conflict **Alternative install method for Claude Desktop (macOS) — cyclopts dependency fix** For anyone hitting package resolution errors with `uvx apple-mail-mcp@latest`, the fix is to enable pre-release dependencies explicitly: In your `claude_desktop_config.json`: ```json "apple-mail": { "command": "uvx", "args": ["--prerelease=allow", "apple-mail-mcp@latest"] } ``` The `--prerelease=allow` flag resolves the `cyclopts>=5.0.0a1` dependency conflict that causes the install to fail silently. Conf [Read the thread](https://github.com/imdinu/apple-mail-mcp/issues/75) · 2026-04-28 · closed · external user · 0 comments The remaining reports are on [the project's issue tracker](https://github.com/imdinu/apple-mail-mcp/issues).