apple-suite-mcp

One small Python file that gives Claude (or any MCP client) access to the built-in Apple apps on your Mac: Mail, Contacts, Calendar, Notes, and Reminders.

Because it talks to the Mail app rather than any one email service, it sees every account you've added to Mail — iCloud plus any number of Gmail, Google Workspace, and Exchange accounts side by side — with no OAuth setup and no extra logins.

Why this one

There are several Apple MCPs out there. This one optimizes for four things:

• Multi-account by nature. Google-API MCPs authenticate one account per OAuth grant — five Google accounts means five connector setups and five token refreshes. This server gets every account at once (five Gmails, an iCloud, an Exchange — whatever Mail and Calendar are signed into), because your Mac already did the logging in.

• Minimal. One readable server.py, three dependencies, no Node, no app to install. If you want to know what it does, you can just read it.

• Fast where it matters. Calendar and Reminders use EventKit (Apple's native database API) instead of scripting the Calendar app — hundreds of times faster on real calendars. Mail listing and search read Mail's local SQLite index directly when Full Disk Access is granted (milliseconds even on giant mailboxes), and fall back to AppleScript automatically when it isn't.

• Self-diagnosing. macOS permissions are the hard part of every Apple MCP. python server.py check (or the check_access tool) tells you exactly what's granted, what's missing, and which System Settings pane fixes it.

Related MCP server: mac-mcp

Setup

Easy mode — let your AI install it

If you use Claude Code (or any coding agent), paste this and let it drive:

Read https://github.com/travisthetrashpanda/apple-suite-mcp and install it for me: clone it, register it with my MCP client, then run its check command and walk me through fixing any macOS permissions it reports missing.

The agent handles cloning and registration, and check tells it exactly which System Settings pane to point you at; you just click Allow when macOS asks. (Sensible to read what you're installing first — it's one Python file.)

Manual mode

Requires macOS and uv (brew install uv).

git clone https://github.com/travisthetrashpanda/apple-suite-mcp.git ~/apple-suite-mcp

Claude Code:

claude mcp add --scope user apple -- uv run --directory ~/apple-suite-mcp python server.py

Claude Desktop / any MCP client — add to your MCP config (e.g. claude_desktop_config.json):

{
  "mcpServers": {
    "apple": {
      "command": "uv",
      "args": ["run", "--directory", "/Users/YOU/apple-suite-mcp", "python", "server.py"]
    }
  }
}

Use the full path to uv (usually /opt/homebrew/bin/uv) if your client doesn't inherit your shell's PATH.

Permissions (one-time)

Run the diagnosis and follow what it tells you:

cd ~/apple-suite-mcp && uv run python server.py check

• Automation (Mail, Contacts, Notes): macOS prompts on first use — click Allow.

• Calendars & Reminders: set the host app (e.g. Claude) to Full Access in System Settings → Privacy & Security.

• Full Disk Access (optional): enables the fast mail path. Without it, everything still works — large mailboxes are just slow (~30s per query). This is a broad grant; read the code and decide for yourself. Note that this one takes two grants — see below.

Gotcha: Full Disk Access needs two entries, not one. In System Settings → Privacy & Security → Full Disk Access, enable both your host app (e.g. "Claude") and "uv". macOS grants this permission per executable, and the server runs as a uv-launched subprocess with its own permission identity — so granting the app alone isn't enough.

Symptom of the missing grant: mail_search and mail_messages time out while check keeps reporting full_disk_access: "no access", no matter how many times you toggle the app or restart the machine. Switching on "uv" flips it to "ok — fast mail path active" immediately, with no relaunch needed.

Try it

what's unread across my inboxes?

search all my accounts for emails from the DMV

what's on my calendar this week?

remind me Thursday at 9am to renew the registration

find my note about the wifi setup

Scoping access (optional)

macOS permissions are per-app, not per-account — once the host app can control Mail, it can see every account on the Mac. If you want tighter control (say, a shared work/personal machine), copy config.example.json to config.json and list what the server is allowed to see:

{
  "mail_accounts": ["Personal"],
  "calendars": ["Home", "Family"],
  "reminder_lists": ["Reminders"],
  "note_folders": ["Notes"],
  "disabled_tools": ["mail_send"]
}

Anything not listed is invisible to every tool — it can't be listed, read, searched, or modified. Omit a key (or the whole file) to allow everything of that kind. disabled_tools removes tools entirely (they're never even registered with the MCP client). check_access reports the active scoping.

Tools

Test any tool from the command line without an MCP client:

uv run python server.py test mail_unread_counts
uv run python server.py test mail_messages '{"account": "Work", "limit": 5}'

Safety notes

• mail_trash uses Mail's normal reversible delete (messages go to the account's Trash). There is deliberately no permanent-delete tool.

• mail_send sends real email through your accounts; MCP clients should confirm with the user before calling it.

• Everything runs locally — nothing is sent anywhere except by mail_send.

Limitations

• macOS only; the target apps must be configured (Mail needs at least one account).

• The first Mail query right after Mail launches can time out while it syncs — retry after a minute.

• Without Full Disk Access, very large mailboxes take ~30s per query and cross-account search (mail_search with no account) is unavailable.

• Nested mail folders are addressed by their full path (e.g. "[Gmail]/All Mail").

Credits

• sweetrb/apple-mail-mcp — the project that proved the scripted-Mail approach and inspired this one.

• krmj22/macos-mcp — the idea of reading Mail's Envelope Index directly instead of fighting slow AppleScript reads.

Say thanks

This project is free to use, no strings attached. If it's useful to you, a ⭐ on this repo or a shout-out to @travisthetrashpanda is always appreciated — and if you build something on top of it, a link back here helps others find it.

License

MIT