Troubleshooting¶

Common issues and their solutions.

Full Disk Access¶

Symptom: apple-mail-mcp index fails with permission errors, or the index has 0 emails.

Cause: The indexer reads .emlx files from ~/Library/Mail/V10/, which macOS protects.

Fix:

Open System Settings
Go to Privacy & Security → Full Disk Access
Add and enable your terminal app (Terminal.app, iTerm2, Warp, etc.)
Restart your terminal (required for changes to take effect)

Note

The MCP server itself does not need Full Disk Access — only the index and rebuild commands do. Once the index is built, the server uses disk-based sync which works without FDA.

Empty Search Results¶

Symptom: search() returns no results for queries you know should match.

Possible causes:

No index built yet. Run apple-mail-mcp index --verbose first. Without the index, only JXA-based search is available (limited to a single mailbox).
Too many keywords. FTS5 uses AND semantics — all terms must match. Use 2–3 specific keywords instead of full sentences.
```
Bad:  "Can you find the email about the quarterly budget meeting?"
Good: "quarterly budget"
```
Index is stale. Check with apple-mail-mcp status. If the index is old, run apple-mail-mcp rebuild or start the server with --watch for real-time updates.
Mailbox excluded. By default, Drafts is excluded from search. Check APPLE_MAIL_INDEX_EXCLUDE_MAILBOXES in your configuration.

Startup Timeout (v0.1.5 and earlier)¶

Symptom: The MCP server hangs for 60+ seconds on startup, or times out entirely. Common with large mailboxes (100K+ emails).

Cause: In v0.1.5 and earlier, the startup sync was blocking — the server waited for the full index reconciliation before accepting tool calls.

Fix: Upgrade to v0.1.6+, which runs sync in a background thread. The server starts immediately and search results become available within seconds as the sync completes.

pipx upgrade apple-mail-mcp

Index Rebuild After Upgrade¶

Symptom: After upgrading, search returns unexpected results or get_attachment() doesn't work.

Cause: Schema changes between versions (e.g., v0.1.3 added attachment metadata in schema v4).

Fix:

apple-mail-mcp rebuild

This drops and recreates the index from scratch.

Mail.app Not Running¶

Symptom: JXA-based tools (list_accounts, list_mailboxes, get_emails, get_email) fail with errors.

Cause: Apple Mail must be running for JXA (JavaScript for Automation) to communicate with it.

Fix: Open Mail.app. It can be minimized — it just needs to be running.

Tip

FTS5-based search (search() with scope all, subject, sender, or body) works even when Mail.app is closed, since it queries the local SQLite index.

`osascript` Errors¶

Symptom: Errors mentioning osascript or "script execution timed out."