apple-mail-mcp

apple-mail-mcp is a Go Model Context Protocol (MCP) server for macOS that gives MCP-compatible assistants programmatic access to Mail.app for listing accounts/mailboxes, searching and reading messages, sending drafts/emails, and unread-count workflows.

Prerequisites

• macOS 12+
• Mail.app configured with at least one account
• Go 1.22+ (only required for building from source)

Installation

1. One-click for Claude Desktop

Download apple-mail-mcp.mcpb from the latest release and double-click it. Claude Desktop installs and registers the server automatically.

2. One-line install (recommended for Claude Code or both clients)

curl -fsSL https://raw.githubusercontent.com/maximbilan/apple-mail-mcp-go/main/install.sh | sh

This installer:

• Detects macOS architecture and installs ~/.local/bin/apple-mail-mcp
• Uses local go build/go install when Go exists, otherwise downloads the latest release binary and verifies SHA256
• Detects Claude Desktop and/or Claude Code and offers registration

3. Build from source (Go developers)

go install github.com/maximbilan/apple-mail-mcp-go/cmd/apple-mail-mcp@latest
apple-mail-mcp install

4. Manual configuration

Claude Desktop config path:

~/Library/Application Support/Claude/claude_desktop_config.json

Add/update:

{
  "mcpServers": {
    "apple-mail": {
      "command": "/Users/<you>/.local/bin/apple-mail-mcp",
      "args": []
    }
  }
}

Claude Code:

claude mcp add apple-mail "$HOME/.local/bin/apple-mail-mcp" --scope user

Permissions

The first time osascript controls Mail.app, macOS shows an Automation permission prompt. Grant access for the calling process (for example Terminal, Claude Desktop, or Claude Code). If needed, manage this at:

System Settings -> Privacy & Security -> Automation

Tool Reference

Generated from registered tools via:

go run ./cmd/apple-mail-mcp tools-docs

| Name | Params | Description | |---|---|---| | list_accounts | none | List account names configured in Mail.app. | | list_mailboxes | account (string, required) | List mailboxes for an account with unread counts. | | search_messages | account (required), mailbox, sender_contains, subject_contains, unread_only, date_from, date_to, limit | Search messages with server-side filters. | | get_message | message_id (required), include_body | Get message metadata and optionally full body. | | get_unread_count | account (optional) | Get total and per-mailbox unread counts. | | send_email | to, subject, body, cc, bcc, account | Send a plaintext email immediately. | | create_draft | to, subject, body, cc, bcc, account | Create a draft email without sending. | | mark_as_read | message_ids, read | Mark messages as read/unread (max 100 ids). |

Running

Start over stdio transport:

apple-mail-mcp --log-level info

Read-only mode (write tools hidden):

apple-mail-mcp --read-only

Known Limitations

• Some Mail messages can have missing/malformed date metadata. search_messages falls back from date sent to date received, and date can be empty when unavailable.
• Gmail label model can surface All Mail semantics. search_messages mailbox output reflects the mailbox requested in the query (for example INBOX) to avoid confusion.

Integration Tests

Integration tests require Mail.app on macOS and explicit build tag:

go test ./tests/integration -tags=integration -v

Troubleshooting

• Mail.app not responding:
  • Open Mail.app once and ensure account sync completes.
• Permission denied:
  • Re-check macOS Automation permissions for the process invoking the server.
• AppleScript timeout:
  • Open Mail.app, wait for sync to settle, then retry.
  • Increase timeout with APPLE_MAIL_MCP_TIMEOUT (e.g. 120s or 180).
• Config did not update:
  • Restart Claude Desktop and run claude mcp list for Claude Code.

Release Validation Checklist

Before creating a public release:

go build ./...
go vet ./...
go test ./... -race

Install path smoke checks:

./install.sh
apple-mail-mcp install --yes
apple-mail-mcp uninstall --yes

Uninstall

./uninstall.sh

Or if installed from go install:

apple-mail-mcp uninstall

License

MIT