Apple Mail MCP
About
Apple Mail MCP server with full-coverage FTS5 body search. Reliable on large mailboxes where AppleScript-based servers timeout.
Details
- License
- GPL-3.0
Explore
- Full-coverage body search via FTS5 index
- 8 tools: list accounts, mailboxes, get emails, search, extract links and attachments
- ~3ms single email fetch via disk-first .emlx reading
- ~1ms list accounts and ~5ms 50-email listing via direct SQLite reads
- Reliable on large mailboxes (tested on ~73K messages)
- CLI commands for all tools (JSON output)
Setting up with Highlight
This MCP is not yet compatible with Highlight’s one-click setup. However, you can still use it with Highlight by following these steps:
- Download and install Highlight from highlightai.com/download
- Navigate to the plugins tab and select "Add Custom Plugin"
-
Configure the plugin with the settings below
Plugin Name
Apple Mail MCPCommand (node, npx, python, etc.)Please refer to the README for specific instructions on how to obtain API keys or other required environment variables.
- Enable "Start Automatically" if you want the plugin to start when Highlight launches
From the repository
pipx install apple-mail-mcp
Add to your MCP client:
{
"mcpServers": {
"mail": {
"command": "apple-mail-mcp"
}
}
}
apple-mail-mcp init # writes ~/.apple-mail-mcp/config.toml
Writes a commented config file you can edit to set defaults like your
primary account or mailbox. Every key has a matching APPLE_MAIL_* env
var if you prefer environment-based config. See
Configuration
for the full schema and precedence rules.
All tools are also available as standalone CLI commands (no MCP server needed):
apple-mail-mcp search "quarterly report" --scope subject
apple-mail-mcp search "invoice" --after 2026-01-01 --limit 10
apple-mail-mcp read 12345
apple-mail-mcp emails --filter unread --limit 10
apple-mail-mcp accounts
apple-mail-mcp mailboxes --account Work
apple-mail-mcp extract 12345 invoice.pdf
All commands output JSON. Generate a Claude Code skill for CLI-based access:
apple-mail-mcp integrate claude > ~/.claude/skills/apple-mail.md
| Tool | Purpose |
|------|---------|
| list_accounts() | List email accounts |
| list_mailboxes(account?) | List mailboxes |
| get_emails(filter?, limit?) | Get emails — all, unread, flagged, today, last_7_days |
| get_email(message_id) | Get single email with full content + attachments |
| search(query, scope?, before?, after?, highlight?) | Search — all, subject, sender, body, attachments |
| get_email_links(message_id) | Extract links from an email |
| get_email_attachment(message_id, filename) | Extract attachment content |
| get_attachment(message_id, filename) | Deprecated — use get_email_attachment() |
Claude Desktop / Cursor
Paste into your MCP client config file to install this server.
{
"mcpServers": {
"apple mail mcp": {
"apple-mail-mcp": {
"command": "apple-mail-mcp"
}
}
}
}McpServers
{
"apple-mail-mcp": {
"command": "apple-mail-mcp"
}
}<!-- mcp-name: io.github.imdinu/apple-mail-mcp -->
<p align="center">
</p>
The only Apple Mail MCP server with full-coverage body search — reliable on large mailboxes where AppleScript-based servers timeout. 8 tools for reading, searching, and extracting email content.
Read the docs for the full guide.
Quick Start
pipx install apple-mail-mcp
Add to your MCP client:
{
"mcpServers": {
"mail": {
"command": "apple-mail-mcp"
}
}
}
Build the Search Index (Recommended)
```bash
Sign in to leave a review
Use Google, GitHub, or an email account so ratings stay tied to real people.
No reviews posted yet.
