Skip to main content
Glama

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

mail_status

Index health and counts

No

mail_list_accounts

Mail accounts

No

mail_list_mailboxes

Mailboxes, optionally for one account

No

mail_get_emails

Messages in a mailbox, with an unread/flagged/today filter

No

mail_get_email

One message with full body and attachments

No

mail_search

FTS5 search over subject, sender, body or attachments

No

mail_get_links

Links found in one message

No

mail_index_rebuild

Rebuild the FTS5 index

Local index only

mail_send_message

Send a new message

Yes, needs full_access

mail_move_message

Move or archive a message

Yes

mail_mark_message

Mark read or unread

Yes

calendar_list_events

Events between two ISO datetimes

No

reminders_list

Open reminders, optionally in one list

No

contacts_search

Search contacts

No

macpilot_health

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 with xcode-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 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.

Configure a client

Claude Code:

claude mcp add --transport stdio macpilot -- uv run --directory /path/to/macpilot-mcp macpilot-mcp serve

OpenCode, 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/Mail without 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_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.

  • mail_move_message and mail_mark_message work under safe_manage. They change your mailbox.

  • serve --read-only sets the profile to safe_readonly and blocks all three write tools. Read tools keep working.

  • calendar_list_events, reminders_list and contacts_search do 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.db and 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 index or mail_index_rebuild call. Run uv run macpilot-mcp index again 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 -q

License

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 tools
calendar_list_eventsCalendar List EventsD

Events in window (ISO datetimes).

Inputs: end_iso (required), start_iso (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_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_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

    C2.8/5.0

    Scored across 15 tools

    Disambiguation4/5

    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.

    Naming Consistency4/5

    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_*.

    Tool Count4/5

    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.

    Completeness3/5

    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

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      B
      quality
      D
      maintenance
      Enables 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.
      24
      1
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables 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
    • A
      license
      Not graded
      quality
      B
      maintenance
      Exposes 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