Skip to content
Back to search

swift-mailmcp

An MCP server to automate Apple Mail in the least disastrous way possible

Safety scan

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

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/rcarmo--swift-mailmcp/badge.svg)](/listings/rcarmo--swift-mailmcp)

HTML

<a href="/listings/rcarmo--swift-mailmcp"><img src="/api/listings/rcarmo--swift-mailmcp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

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 · 55 lines
  1. # MailMCP
  2. A Swift MCP server for organizing messages in Apple Mail.
  3. - **Scope.** MailMCP deliberately limits agents to organizing mail. They can discover folders, read metadata, search available content, and file messages. Sending email and accessing account credentials are outside the tool surface.
  4. - **Local automation.** A signed app sends native Apple Events using Mail's scripting dictionary in the logged-in macOS session. The server listens on loopback for sandboxed agents. Keep the bearer token private.
  5. - **Requirements.** This source preview builds with Swift 5.10 or later from Xcode or the Command Line Tools. The deployment target is macOS 13 to leave room for VM use. Live Mail automation has been tested on macOS 27.2.1 (26B131) on Apple silicon.
  6. ## Get started
  7. 1. Build and sign the app, create a bearer token, and grant Mail Automation permission. [Setup](docs/setup.md)
  8. 2. Connect your MCP client to [http://127.0.0.1:8765/mcp](http://127.0.0.1:8765/mcp) using Streamable HTTP and the bearer token.
  9. 3. Run `list_mailboxes` to discover the account IDs, folder paths, and mailbox IDs.
  10. ## Tools and prompts
  11. | Tool | Use |
  12. | --- | --- |
  13. | `list_mailboxes` | Discover account IDs, canonical nested mailbox paths, and stable `mailboxId` UUIDs. |
  14. | `list_messages` | Page through metadata for a mailbox, an account, or all physical mailboxes. |
  15. | `search_messages` | Search sender and subject by substring, or filter by exact `to` and `cc` addresses. Set `includeBody` for plain-text search. |
  16. | `find_similar_messages` | Find copies and related mail by matching Message-ID, subject with common reply prefixes removed, and sender. Scores rank hits within each page. |
  17. | `move_message` | Queue one move and return its operation ID as soon as the request is recorded. |
  18. | `move_messages` | Queue up to 50 moves in one call, with individual operation IDs and outcomes. |
  19. | `get_move_status` | Read a recorded move or request a bounded reconciliation. Expired IDs remain reserved. |
  20. The `find_mail` and `file_mail` prompts guide clients through search and filing.
  21. ### Search and listing
  22. - Use the account, full nested path, and optional `mailboxId` returned by `list_mailboxes`. Use `null` for the account of an On My Mac folder. Same-name folders can coexist at different paths. A path-derived ID can change if its folder is renamed or moved.
  23. - Mailbox-scoped searches default to newest first by sent date, with received date as a fallback. Account-wide searches default to Mail's enumeration order. Set `sort` explicitly to choose either order.
  24. - Pass an exact `to` or `cc` address with or without a text query. All supplied filters must match. Recipient filters include both recipient arrays in the result. Set `includeRecipients` for text-only queries that also need addresses.
  25. - Follow `nextOffset` until it is null, including after a page with no matches. Mail sync and filing can shift page boundaries. Searches cover physical mailboxes and the content Mail exposes.
  26. Example search arguments.
  27. ```json
  28. {
  29. "mailbox": {"accountId": "ACCOUNT_ID", "path": ["Sent Messages"]},
  30. "to": "person@example.com",
  31. "limit": 5
  32. }
  33. ```
  34. ## Filing and operations
  35. - [Single and batch moves](docs/moves.md) covers request examples, acknowledgement, status, and verification.
  36. - [Operations](docs/operations.md) covers the 90-day journal retention policy, diagnostics, and timeouts.
  37. ## License and credits
  38. MailMCP is distributed under the [MIT License](LICENSE).
  39. The Mail bridge follows the Apple Events approach used by [apple-mail-jxa-mcp](https://github.com/jakobjhartmann/apple-mail-jxa-mcp). The MCP interface follows [µMCP](https://github.com/rcarmo/umcp)'s small dispatcher, discoverable tool and prompt schemas, and separation of protocol handling from app operations.

Ratings and comments

Sign in to rate this skill.

Sign in

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