apple-mail

apple-mail-mcp is a fast MCP server for Apple Mail that leverages batch JXA for rapid email fetching and a disk-based FTS5 index to enable extremely fast body search. It exposes tools to list accounts and mailboxes, fetch emails (with full content and attachments), and perform targeted searches across subject, sender, body, and attachments. After installing the package, add the server to your MCP client configuration (as shown in the quick start) and run the server in watch mode so the MCP bridge can respond to client requests in real time. You can also run a dedicated index build to initialize or refresh the search index; this step may require additional system permissions depending on your macOS security settings.

Prerequisites:

• Python 3.11+ (or a compatible Python environment)
• pipx (recommended for Python-based MCP servers)
• macOS (Apple Mail integration relies on macOS features)

Install the Apple Mail MCP server:

1. Install via pipx (recommended):

pipx install apple-mail-mcp

2. Verify installation:

apple-mail-mcp --version

3. (Optional) Build the search index after installation:

# Requires Full Disk Access for Terminal
# System Settings → Privacy & Security → Full Disk Access → Add Terminal
apple-mail-mcp index --verbose

Integrate with an MCP client:

• In your MCP client configuration, reference the server by its command name as shown below:

{
  "mcpServers": {
    "mail": {
      "command": "apple-mail-mcp"
    }
  }
}

For development or alternative runtimes, you can run the server directly if you prefer not to use pipx:

# If installed elsewhere or from source:
python -m apple_mail_mcp

Notes and tips:

• You can customize the default account used by the server via the APPLE_MAIL_DEFAULT_ACCOUNT environment variable to control which mailbox is used by default.
• The default index path is ~/.apple-mail-mcp/index.db; you can override this with APPLE_MAIL_INDEX_PATH if needed.
• If you encounter macOS privacy prompts, ensure Terminal has Full Disk Access to allow indexing and data access.
• The server supports a variety of MCP tools exposed by the package: list_accounts(), list_mailboxes(account?), get_emails(filter?, limit?), get_email(message_id), search(query, scope?), and get_attachment(message_id, filename).
• When using the MCP client, consider enabling the verbose index build during initial setup to ensure the search index is ready for fast queries.
• Ensure you are running compatible versions of macOS and Python to avoid runtime issues related to system integrations.
• If you plan to migrate from apple-mcp, note the scope limitations and the improved performance and features of apple-mail-mcp as documented in the project notes.