Skip to content
Back to search

macpilot-mcp

One local MCP server for Apple Mail, Calendar, Reminders and Contacts on macOS

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/udit19199--macpilot-mcp/badge.svg)](/listings/udit19199--macpilot-mcp)

HTML

<a href="/listings/udit19199--macpilot-mcp"><img src="/api/listings/udit19199--macpilot-mcp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

git clone <repo-url> macpilot-mcp
cd macpilot-mcp
uv sync
uv run macpilot-mcp index    # build the search index once
uv run macpilot-mcp status   # print index counts

`index` prints how many messages it wrote and the database path. The first run reads your whole Mail folder, so expect it to take a while on a large mailbox.

Start the server:

uv run macpilot-mcp serve

By default it speaks MCP over stdio. To use HTTP on loopback:

uv run macpilot-mcp serve --transport streamable-http --port 8765

The HTTP transport refuses any host other than `127.0.0.1`.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 145 lines
  1. # macpilot-mcp
  2. One local MCP server for Apple Mail, Calendar, Reminders and Contacts on macOS. It reads the same data the Apple apps show, keeps a full-text search index of your mail on disk, and gives an AI client a small set of tools for those four apps.
  3. Version 0.1.0. macOS only.
  4. ## What it does
  5. - Searches all mail with SQLite FTS5 and BM25 ranking, including message bodies.
  6. - Lists accounts, mailboxes and messages, and opens one message with its attachments.
  7. - Moves, marks and sends mail, gated by a safety profile.
  8. - Lists calendar events in a time window.
  9. - Lists open reminders.
  10. - Searches contacts by name, email address or phone number.
  11. - Reports index and domain health.
  12. Mail reads go to the files in `~/Library/Mail` first, so opening a message does not start Mail or AppleScript. Calendar, Reminders and Contacts go through a small Swift helper that uses EventKit.
  13. ## Tools
  14. | Tool | What it does | Writes |
  15. | --- | --- | --- |
  16. | `mail_status` | Index health and counts | No |
  17. | `mail_list_accounts` | Mail accounts | No |
  18. | `mail_list_mailboxes` | Mailboxes, optionally for one account | No |
  19. | `mail_get_emails` | Messages in a mailbox, with an unread/flagged/today filter | No |
  20. | `mail_get_email` | One message with full body and attachments | No |
  21. | `mail_search` | FTS5 search over subject, sender, body or attachments | No |
  22. | `mail_get_links` | Links found in one message | No |
  23. | `mail_index_rebuild` | Rebuild the FTS5 index | Local index only |
  24. | `mail_send_message` | Send a new message | Yes, needs `full_access` |
  25. | `mail_move_message` | Move or archive a message | Yes |
  26. | `mail_mark_message` | Mark read or unread | Yes |
  27. | `calendar_list_events` | Events between two ISO datetimes | No |
  28. | `reminders_list` | Open reminders, optionally in one list | No |
  29. | `contacts_search` | Search contacts | No |
  30. | `macpilot_health` | Index and domain health | No |
  31. ## Requirements
  32. - macOS with Mail, Calendar, Reminders and Contacts set up.
  33. - Python 3.11 or newer.
  34. - [uv](https://docs.astral.sh/uv/).
  35. - Xcode Command Line Tools, for `swiftc`. The Calendar, Reminders and Contacts helper compiles on first use. Install with `xcode-select --install`.
  36. ## Install
  37. ```sh
  38. git clone <repo-url> macpilot-mcp
  39. cd macpilot-mcp
  40. uv sync
  41. uv run macpilot-mcp index # build the search index once
  42. uv run macpilot-mcp status # print index counts
  43. ```
  44. `index` prints how many messages it wrote and the database path. The first run reads your whole Mail folder, so expect it to take a while on a large mailbox.
  45. Start the server:
  46. ```sh
  47. uv run macpilot-mcp serve
  48. ```
  49. By default it speaks MCP over stdio. To use HTTP on loopback:
  50. ```sh
  51. uv run macpilot-mcp serve --transport streamable-http --port 8765
  52. ```
  53. The HTTP transport refuses any host other than `127.0.0.1`.
  54. ## Configure a client
  55. Claude Code:
  56. ```sh
  57. claude mcp add --transport stdio macpilot -- uv run --directory /path/to/macpilot-mcp macpilot-mcp serve
  58. ```
  59. OpenCode, in `opencode.json`:
  60. ```json
  61. {
  62. "mcp": {
  63. "macpilot": {
  64. "type": "local",
  65. "command": [
  66. "uv",
  67. "run",
  68. "--directory",
  69. "/path/to/macpilot-mcp",
  70. "macpilot-mcp",
  71. "serve"
  72. ],
  73. "enabled": true
  74. }
  75. }
  76. }
  77. ```
  78. Replace `/path/to/macpilot-mcp` with the folder you cloned into.
  79. ## macOS permissions
  80. - Full Disk Access. The app that starts the server, such as Terminal, iTerm2 or your editor, needs this to read `~/Library/Mail` without prompts. Add it in System Settings > Privacy & Security > Full Disk Access. Quit and reopen the app after adding it.
  81. - Automation. macOS asks whether the app may control Mail. Allow it. Mail writes use AppleScript, so the prompt appears on the first write.
  82. - Calendar, Reminders and Contacts. The first call that needs the Swift helper triggers a system prompt for that app. Allow it. The helper is an ad-hoc signed bundle in `~/.apple-mcps/build`.
  83. - If a prompt never appears, run the server once from Terminal so macOS knows which app is asking.
  84. ## Safety
  85. The default profile is `safe_manage`.
  86. - `mail_send_message` needs `MACPILOT_SAFETY_PROFILE=full_access`. At lower profiles it returns a policy error and sends nothing. Set the profile in the server environment before start.
  87. - `mail_move_message` and `mail_mark_message` work under `safe_manage`. They change your mailbox.
  88. - `serve --read-only` sets the profile to `safe_readonly` and blocks all three write tools. Read tools keep working.
  89. - `calendar_list_events`, `reminders_list` and `contacts_search` do not write. The server registers no calendar, reminder or contact write tool.
  90. - No tool deletes mail.
  91. Data handling:
  92. - The index lives in `~/.macpilot-mcp/index.db` and holds sender, subject, date and body text for indexed messages. It is not encrypted. Treat it like a copy of your mail.
  93. - Everything runs locally. The server makes no network calls and sends no telemetry.
  94. - The HTTP transport listens on loopback only.
  95. ## Limitations
  96. - macOS only. There is no Linux or Windows support.
  97. - The index does not update itself. Listing and opening messages read the Mail folder directly, but body search only sees messages written by the last `index` or `mail_index_rebuild` call. Run `uv run macpilot-mcp index` again to catch up.
  98. - Only the 15 tools in the table are exposed. The vendored projects contain more tools that this server does not register.
  99. - Sending needs an account already configured in Mail. The server does not manage accounts or credentials.
  100. - The first Calendar, Reminders or Contacts call can take a few seconds while the helper compiles.
  101. - Large mailboxes produce a large index file and a slow first build.
  102. ## Development
  103. ```sh
  104. uv sync
  105. uv run ruff check src tests
  106. uv run pytest -q
  107. ```
  108. ## License
  109. GPL-3.0-or-later. The mail index code comes from [imdinu/apple-mail-mcp](https://github.com/imdinu/apple-mail-mcp), which is GPL-3.0-or-later. The mail write guard comes from [patrickfreyer/apple-mail-mcp](https://github.com/patrickfreyer/apple-mail-mcp), and the Calendar, Reminders and Contacts bridges come from [JonathanRReed/Apple-MCPs](https://github.com/JonathanRReed/Apple-MCPs); both are MIT. See `NOTICE.md` for the versions used.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.