# Apple Mail

MCP server connecting macOS Apple Mail to coding agents. It searches local messages and reads email bodies directly on your Mac without external IMAP logins.

- MCP server · `type=mcp` · Claude Code, Codex, Cursor, GitHub Copilot, Windsurf (Devin Desktop), Cline, Zed, Gemini CLI · ★ 5
- Author: mgcrea
- License: MIT · policy=link-only · description only; the file stays with the author
- Source: https://github.com/mgcrea/cupertino/tree/HEAD/packages/mail
- Updated: 2026-10-22
- HTML: https://affpapa.org/en/nevibecode/mcp/mgcrea-apple-mail

## What it does

The server taps into local mailbox files on macOS instead of sending credentials to cloud APIs. Operations follow two routes: AppleScript handles account listings, mailbox tallies and mutations, while message lookups read the local SQLite `Envelope Index`. Message bodies and attached files are loaded directly from `.emlx` files on disk.

Two distinct macOS permissions govern operation. Automation grants access to Mail.app events, while Full Disk Access lets the server query the search index and open message files. Without disk access, search fails completely. To avoid giving full disk privileges to your IDE process chain, the author distributes Cupertino (`brew install --cask mgcrea/tap/cupertino`), a signed utility holding the needed entitlement.

All modifications stay locked under `APPLE_MAIL_ALLOW_WRITES="0"` unless changed deliberately. As a result, agents cannot delete or transmit messages right after setup. Whenever an operation fails silently, running `apple_mail_diagnostics` pinpoints the missing permission.

## Requirements
- Needs: Node.js (commands run via npx)
- Environment variables: `APPLE_MAIL_ALLOW_WRITES`, `APPLE_MAIL_ACCOUNTS`, `APPLE_MAIL_ALLOW_FILE_SEND` — keys and tokens: ask the human for the values, never commit them or put them in shared files.

## Install

### Claude Code (native platform)

**Platform CLI**
```bash
claude mcp add --env APPLE_MAIL_ALLOW_WRITES=<APPLE_MAIL_ALLOW_WRITES> --env APPLE_MAIL_ACCOUNTS=<APPLE_MAIL_ACCOUNTS> --env APPLE_MAIL_ALLOW_FILE_SEND=<APPLE_MAIL_ALLOW_FILE_SEND> --transport stdio mail -- npx -y @mgcrea/mcp-apple-mail
```
Replace <…> with your own values

### Codex

**Platform CLI**
```bash
codex mcp add mail --env APPLE_MAIL_ALLOW_WRITES=<APPLE_MAIL_ALLOW_WRITES> --env APPLE_MAIL_ACCOUNTS=<APPLE_MAIL_ACCOUNTS> --env APPLE_MAIL_ALLOW_FILE_SEND=<APPLE_MAIL_ALLOW_FILE_SEND> -- npx -y @mgcrea/mcp-apple-mail
```
Replace <…> with your own values

### Cursor

**Config file**
File `.cursor/mcp.json`:
```json
{
    "mcpServers": {
        "mail": {
            "command": "npx",
            "args": [
                "-y",
                "@mgcrea/mcp-apple-mail"
            ],
            "env": {
                "APPLE_MAIL_ALLOW_WRITES": "<APPLE_MAIL_ALLOW_WRITES>",
                "APPLE_MAIL_ACCOUNTS": "<APPLE_MAIL_ACCOUNTS>",
                "APPLE_MAIL_ALLOW_FILE_SEND": "<APPLE_MAIL_ALLOW_FILE_SEND>"
            }
        }
    }
}
```
Replace <…> with your own values

### GitHub Copilot

**Config file**
File `.vscode/mcp.json`:
```json
{
    "servers": {
        "mail": {
            "type": "stdio",
            "command": "npx",
            "args": [
                "-y",
                "@mgcrea/mcp-apple-mail"
            ],
            "env": {
                "APPLE_MAIL_ALLOW_WRITES": "<APPLE_MAIL_ALLOW_WRITES>",
                "APPLE_MAIL_ACCOUNTS": "<APPLE_MAIL_ACCOUNTS>",
                "APPLE_MAIL_ALLOW_FILE_SEND": "<APPLE_MAIL_ALLOW_FILE_SEND>"
            }
        }
    }
}
```
Replace <…> with your own values

### Gemini CLI

**Platform CLI**
```bash
gemini mcp add -e APPLE_MAIL_ALLOW_WRITES=<APPLE_MAIL_ALLOW_WRITES> -e APPLE_MAIL_ACCOUNTS=<APPLE_MAIL_ACCOUNTS> -e APPLE_MAIL_ALLOW_FILE_SEND=<APPLE_MAIL_ALLOW_FILE_SEND> mail npx -y @mgcrea/mcp-apple-mail
```
Replace <…> with your own values

## When to use it
- query local mail threads using SQLite index files
- retrieve message content and attachments from disk
- check mailbox accounts and count unread messages
- draft and send messages through AppleScript when writes are enabled

## Example prompts
- Run `apple_mail_diagnostics` to verify permissions on macOS
- List my configured mail accounts and unread message tallies
- Find recent messages from my accounting team and display their subjects

## Similar
- [Reactive Resume](https://affpapa.org/en/nevibecode/mcp/reactive-resume.md) — MCP server · ★ 44908
- [screenpipe](https://affpapa.org/en/nevibecode/mcp/screenpipe.md) — MCP server · ★ 22082
- [Inbox Zero](https://affpapa.org/en/nevibecode/mcp/inbox-zero.md) — MCP server · ★ 12826
- [kaneo](https://affpapa.org/en/nevibecode/mcp/kaneo.md) — MCP server · ★ 9623
- [Mindwtr](https://affpapa.org/en/nevibecode/mcp/mindwtr.md) — MCP server · ★ 2330
- [Azure DevOps (ADO)](https://affpapa.org/en/nevibecode/mcp/azure-devops-ado.md) — MCP server · ★ 2071

## Other versions with the same name
- [Apple Mail · jonathanrreed](https://affpapa.org/en/nevibecode/mcp/apple-mail.md) — ★ 31

From the same set: [mgcrea/cupertino](https://affpapa.org/en/nevibecode/by/mgcrea/cupertino.md) — 6 cards

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md