macpilot-mcp
Provides local tools for Apple Mail, Calendar, Reminders, and Contacts, including full-text mail search, message listing/opening/moving/marking/sending with safety controls, calendar event listing, open reminder listing, and contact search.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@macpilot-mcp search my mail for unread messages from Sarah"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
macpilot-mcp
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.
Version 0.1.0. macOS only.
What it does
Searches all mail with SQLite FTS5 and BM25 ranking, including message bodies.
Lists accounts, mailboxes and messages, and opens one message with its attachments.
Moves, marks and sends mail, gated by a safety profile.
Lists calendar events in a time window.
Lists open reminders.
Searches contacts by name, email address or phone number.
Reports index and domain health.
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.
Related MCP server: Nico Apple MCP
Tools
Tool | What it does | Writes |
| Index health and counts | No |
| Mail accounts | No |
| Mailboxes, optionally for one account | No |
| Messages in a mailbox, with an unread/flagged/today filter | No |
| One message with full body and attachments | No |
| FTS5 search over subject, sender, body or attachments | No |
| Links found in one message | No |
| Rebuild the FTS5 index | Local index only |
| Send a new message | Yes, needs |
| Move or archive a message | Yes |
| Mark read or unread | Yes |
| Events between two ISO datetimes | No |
| Open reminders, optionally in one list | No |
| Search contacts | No |
| Index and domain health | No |
Requirements
macOS with Mail, Calendar, Reminders and Contacts set up.
Python 3.11 or newer.
uv.
Xcode Command Line Tools, for
swiftc. The Calendar, Reminders and Contacts helper compiles on first use. Install withxcode-select --install.
Install
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 countsindex 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 serveBy default it speaks MCP over stdio. To use HTTP on loopback:
uv run macpilot-mcp serve --transport streamable-http --port 8765The HTTP transport refuses any host other than 127.0.0.1.
Configure a client
Claude Code:
claude mcp add --transport stdio macpilot -- uv run --directory /path/to/macpilot-mcp macpilot-mcp serveOpenCode, in opencode.json:
{
"mcp": {
"macpilot": {
"type": "local",
"command": [
"uv",
"run",
"--directory",
"/path/to/macpilot-mcp",
"macpilot-mcp",
"serve"
],
"enabled": true
}
}
}Replace /path/to/macpilot-mcp with the folder you cloned into.
macOS permissions
Full Disk Access. The app that starts the server, such as Terminal, iTerm2 or your editor, needs this to read
~/Library/Mailwithout prompts. Add it in System Settings > Privacy & Security > Full Disk Access. Quit and reopen the app after adding it.Automation. macOS asks whether the app may control Mail. Allow it. Mail writes use AppleScript, so the prompt appears on the first write.
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.If a prompt never appears, run the server once from Terminal so macOS knows which app is asking.
Safety
The default profile is safe_manage.
mail_send_messageneedsMACPILOT_SAFETY_PROFILE=full_access. At lower profiles it returns a policy error and sends nothing. Set the profile in the server environment before start.mail_move_messageandmail_mark_messagework undersafe_manage. They change your mailbox.serve --read-onlysets the profile tosafe_readonlyand blocks all three write tools. Read tools keep working.calendar_list_events,reminders_listandcontacts_searchdo not write. The server registers no calendar, reminder or contact write tool.No tool deletes mail.
Data handling:
The index lives in
~/.macpilot-mcp/index.dband holds sender, subject, date and body text for indexed messages. It is not encrypted. Treat it like a copy of your mail.Everything runs locally. The server makes no network calls and sends no telemetry.
The HTTP transport listens on loopback only.
Limitations
macOS only. There is no Linux or Windows support.
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
indexormail_index_rebuildcall. Runuv run macpilot-mcp indexagain to catch up.Only the 15 tools in the table are exposed. The vendored projects contain more tools that this server does not register.
Sending needs an account already configured in Mail. The server does not manage accounts or credentials.
The first Calendar, Reminders or Contacts call can take a few seconds while the helper compiles.
Large mailboxes produce a large index file and a slow first build.
Development
uv sync
uv run ruff check src tests
uv run pytest -qLicense
GPL-3.0-or-later. The mail index code comes from imdinu/apple-mail-mcp, which is GPL-3.0-or-later. The mail write guard comes from patrickfreyer/apple-mail-mcp, and the Calendar, Reminders and Contacts bridges come from JonathanRReed/Apple-MCPs; both are MIT. See NOTICE.md for the versions used.
Available Tools
15 toolscalendar_list_eventsCalendar List EventsD
Events in window (ISO datetimes).
Inputs: end_iso (required), start_iso (required), limit.
contacts_searchContacts SearchB
Search contacts by name/email/phone.
Inputs: query (required), limit.
macpilot_healthMacpilot HealthC
Server health across domains.
Inputs: no named parameters. Returns: object
mail_get_emailMail Get EmailB
Single email with full content + attachments (disk-first ~3ms).
Inputs: message_id (required). Returns: object
mail_get_emailsMail Get EmailsC
List emails from one mailbox (disk-first, no full scan).
Inputs: limit, filter, account, mailbox.
mail_get_linksMail Get LinksC
Extract hyperlinks from one email.
Inputs: message_id (required).
mail_index_rebuildMail Index RebuildC
(Re)build the FTS5 index from disk. Run again when the index is stale.
Inputs: mailbox. Returns: object
mail_list_accountsMail List AccountsB
List configured Mail accounts.
Inputs: no named parameters.
mail_list_mailboxesMail List MailboxesB
List mailboxes, optionally for one account.
Inputs: account.
mail_mark_messageMail Mark MessageC
Mark read/unread.
Inputs: message_id (required), is_read. Returns: object
mail_move_messageMail Move MessageC
Move/archive a message.
Inputs: message_id (required), target_mailbox (required). Returns: object
mail_searchMail SearchB
FTS5 full-mailbox search with BM25 ranking. Index required for body scope.
Inputs: query (required), after, limit, scope, +3 more.
mail_send_messageMail Send MessageB
Send email (full_access safety profile required).
Inputs: to (required), body (required), subject (required), from_account. Returns: object
mail_statusMail StatusC
FTS5 index health + stats.
Inputs: no named parameters. Returns: object
reminders_listReminders ListC
Open reminders, optionally in one list.
Inputs: limit, list_id.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 15 tools
Most tools target a distinct resource+action within a clear domain prefix (mail, calendar, reminders, contacts). The main confusion risk is mail_get_email vs mail_get_emails and mail_search vs mail_get_emails, where plural/singular and list-vs-search boundaries are only resolved by reading descriptions. mail_get_links also partially overlaps with what mail_get_email already returns.
Strong, predictable snake_case domain_action pattern (mail_*, calendar_*, contacts_*), which makes scanning easy. Minor deviations: mail_status and macpilot_health are noun-only with no verb, and reminders_list reverses the verb_noun order used by calendar_list_events and mail_list_*.
15 tools is at the top of the comfortable range and each mail tool earns its place; index maintenance and health checks are justified given the FTS5 dependency. The surface is a bit mail-heavy relative to the four other domains, which get only a single tool each.
Mail coverage is strong (accounts, mailboxes, list/get/search, links, index rebuild, send, move, mark), though delete and reply/forward are absent. Calendar, reminders, and contacts are read-only, so common agent tasks like creating an event or completing a reminder are impossible — a notable lifecycle gap.
Maintenance
Related MCP Connectors
Let your AI agent read and act on your Mail, Calendar, Contacts and more. Works with iCloud.
Mail, Calendar, Messages, Notes, Contacts, Slack on your Mac for AI. Remote needs Pro or free trial.
Mac & Windows: let ChatGPT, Claude & Cursor use your email, calendar, iMessage, Teams, files.
Email inboxes and calendars for AI agents: send, receive, search, draft and schedule.
Related MCP Servers
- AlicenseBqualityDmaintenanceEnables AI agents to interact with macOS applications (Finder, Mail, Contacts, Reminders, Notes, Calendar, TextEdit) using AppleScript. Allows AI assistants to perform tasks like searching contacts, managing files, checking email, and creating reminders through natural language.241MIT
- AlicenseNot gradedqualityBmaintenanceEnables AI assistants to interact with local Apple Calendar, Notes, and Contacts on macOS. Provides tools for creating, reading, updating, and deleting events, notes, and contacts through natural language.MIT
- AlicenseNot gradedqualityBmaintenanceExposes 28 native tools that let an agent list, search, create, complete and delete Apple Calendar events and reminders, read and compose Mail drafts, inspect and script Safari tabs, and take full-screen, window, region or clipboard screenshots. All actions run through host AppleScript and EventKit with confirmation gates on deletes and never send mail automatically.MIT
- AlicenseNot gradedqualityBmaintenanceConnects AI assistants to Apple Mail, Calendar, and Contacts on a Mac, enabling local search, message reading, contact lookup, and optionally sending email or creating calendar events with guarded confirmation.AGPL 3.0