An MCP (Model Context Protocol) server that provides read-only access to macOS Mail.app. It queries the Mail.app SQLite database for message metadata and uses AppleScript to retrieve message bodies and attachments. Designed to work with Claude Code and other MCP-compatible clients.

Requirements#

macOS
Mail.app with at least one configured account
Bun runtime
Automation permission for osascript to access Mail.app (macOS will prompt on first use)

Responsible Use#

This tool reads your email. Please keep the following in mind:

Only run MailGenie locally on your own machine. Never expose it over a network.
Review what MCP permissions your client grants before connecting.
Your email data stays on your machine — MailGenie does not send data anywhere.
Be mindful of what you ask an LLM to do with your email content.

Setup#

git clone git@tangled.org:aparker.io/mailgenie
cd mailgenie
bun install
bun run build

Copy the example MCP config and adjust if needed:

cp .mcp.json.example .mcp.json

Then add the server to your MCP client. For Claude Code, the .mcp.json in the project root is picked up automatically.

Tools#

Tool	Description
`list_accounts`	List all configured Mail.app accounts with message and unread counts
`list_mailboxes`	List mailboxes (folders) with counts, optionally filtered by account
`get_unread_count`	Get unread message count, optionally filtered by account or mailbox
`search_messages`	Search messages by subject, sender, date range, read/flagged status, mailbox, or account
`read_message`	Read the full body of a message by ID, including List-Unsubscribe URLs
`save_attachment`	Save a message attachment to `/tmp/mailgenie/`

Configuration#

Variable	Description	Default
`MAILGENIE_DB_PATH`	Path to Mail.app's Envelope Index SQLite database	`~/Library/Mail/V10/MailData/Envelope Index`

License#

MIT

Clone this repository