Skip to main content
Glama

macos-mcp

Local MCP server for macOS native apps: Mail, Calendar, Reminders, Notes, Messages, and Contacts. One stdio process, zero npm dependencies, Node 20+.

Windows and Linux are not supported. Calendar reads use EventKit (bin/eventkit-cal); Calendar writes and other modules use AppleScript/JXA. No Gmail API, no OAuth, no cloud credentials.

What it is

One MCP server = one mental model: read and organize your Mac life.

Module

App

Prefix

Mail

Mail.app

mail_*

Calendar

Calendar.app

calendar_*

Reminders

Reminders.app

reminders_*

Notes

Notes.app

notes_*

Messages

Messages.app (chat.db)

messages_*

Contacts

Contacts.app

contacts_*

Email is draft-only. mail_draft_email opens a visible draft in Mail.app; it never sends. You review and send manually.

Related MCP server: mac-mcp

Requirements

  • macOS with Mail, Calendar, Reminders, Notes, Messages configured

  • Node.js β‰₯ 20

  • Cursor (or any MCP client that supports stdio)

Install

git clone <your-repo-url> macos-mcp
cd macos-mcp
bash scripts/build-eventkit-cal.sh   # required for fast calendar reads
node scripts/install-mcp.js

Restart Cursor. The installer registers macos-local in ~/.cursor/mcp.json (backs up existing config to .bak).

Manual registration:

{
  "mcpServers": {
    "macos-local": {
      "command": "node",
      "args": ["/absolute/path/to/macos-mcp/bin/macos-mcp.js"]
    }
  }
}

Signatures (mail drafts)

bash scripts/install-mail-signatures.sh

Edit signatures/manifest.json and signatures/*.txt locally. Real signatures are gitignored.

macOS permissions

Grant in System Settings β†’ Privacy & Security:

Permission

Needed for

Calendars β€” Full access for Cursor (MCP) and/or Terminal (CLI smoke tests); the helper may also appear as eventkit-cal

calendar_list_* / calendar_search_events via EventKit

Automation β€” allow Cursor to control Mail, Calendar, Reminders, Notes, Contacts

JXA/AppleScript modules (calendar create/update/delete, Mail, etc.)

Full Disk Access β€” Cursor (or Terminal during testing)

Messages module (~/Library/Messages/chat.db)

On first calendar read, macOS may prompt for Calendar access. If the helper exits with β€œCalendar Full Access required”:

  1. Open System Settings β†’ Privacy & Security β†’ Calendars

  2. Find Cursor (MCP) and/or Terminal (CLI smoke tests)

  3. Enable Full Access (not Write Only / Add Only)

  4. Re-run npm run smoke:calendar or restart the MCP server

Cursor’s Calendar TCC was previously Write Only on this machine; Full Access is required for EventKit reads. Calendar create/update/delete still use Automation (AppleScript) and do not need EventKit Full Access.

Tool index

Mail (mail_*)

Tool

Description

mail_list_accounts

List Mail accounts

mail_list_mailboxes

List mailboxes (optional account filter)

mail_list_messages

List messages in mailbox

mail_search_messages

Search subject/sender

mail_get_message

Full message by id

mail_save_attachments

Save message attachments to a local directory

mail_draft_email

Open new compose draft (never sends)

mail_draft_reply

Open reply draft in thread (never sends)

mail_archive_messages

Move to All Mail

mail_trash_messages

Move to Trash

mail_mark_read

Mark read/unread

mail_move_messages

Move to mailbox

Calendar (calendar_*)

Tool

Description

calendar_list_calendars

List calendars

calendar_list_events

Events in date range

calendar_search_events

Search title/location

calendar_get_event

Full event

calendar_create_event

Create event (optional attendees email list)

calendar_update_event

Update event

calendar_delete_event

Delete event

Reminders (reminders_*)

Tool

Description

reminders_list_lists

List reminder lists

reminders_list

List reminders in a list

reminders_search

Search name/notes

reminders_create

Create reminder

reminders_complete

Mark complete

reminders_delete

Delete reminder

Notes (notes_*)

Tool

Description

notes_list_folders

List folders

notes_list

List notes

notes_search

Search title/body

notes_get

Get note body

notes_create

Create note

notes_append

Append to note

On newer macOS, note body extraction may fail; notes_get returns body_unavailable: true when scripting is restricted.

Calendar list/search use EventKit (typically under a second for a week range). Create/update/delete still use Calendar.app scripting. Build the helper with npm run build:eventkit if bin/eventkit-cal is missing.

Messages (messages_*)

Tool

Description

messages_get_thread

Thread by phone/email substring

messages_list_chats

Recent chats

Requires Full Disk Access. Reads iMessage/SMS locally; no network.

Contacts (contacts_*)

Tool

Description

contacts_list

List contacts (optional: missing email only)

contacts_search

Search by name/email/phone

contacts_get

Full contact card

contacts_create

Create contact

contacts_update

Update contact

contacts_delete

Delete contact

contacts_import_csv

Import Google Contacts CSV (upsert by email)

Architecture

bin/macos-mcp.js           β†’ entrypoint
bin/eventkit-cal           β†’ EventKit CLI (built; not committed)
native/EventKitCal/        β†’ Swift source + Info.plist
src/mcp/server.js          β†’ JSON-RPC MCP (protocol 2024-11-05)
src/mcp/transport.js       β†’ stdio NDJSON
src/mcp/tools.js           β†’ aggregates all module tools
src/runtime/eventkit.js    β†’ spawns eventkit-cal for calendar reads
src/runtime/jxa.js         β†’ generic JXA runner (Application per app)
src/runtime/applescript.js β†’ AppleScript runner + draft email
src/mail/                  β†’ Mail module
src/calendar/              β†’ Calendar module (reads β†’ EventKit; writes β†’ AS/JXA)
...

EventKit vs JXA vs AppleScript

  • EventKit (bin/eventkit-cal): calendar_list_calendars, calendar_list_events, calendar_search_events.

  • JXA (osascript -l JavaScript): read/list/search most other app data; calendar alarm attach after create; generic runJxa(appName, body, args).

  • AppleScript: mail_draft_email, calendar create/update/delete/get, and contacts create/update (JXA make is unreliable on modern Calendar.app and Contacts.app).

Response shapes: lists include count; domain keys vary (items, events, reminders, notes, chats, contacts). Errors throw and return MCP isError: true.

Mail.app quirks

  • Saved drafts may retain a leading newline Mail adds on save; the compose window is usually correct.

  • AppleScript does not auto-attach Mail.app signature prefs; this server appends from signatures/ files instead.

What it is NOT

  • No Gmail API, Microsoft Graph, or OAuth

  • No auto-send email

  • No npm publish (private: true)

  • No telemetry or network calls in server code

Development

npm run build:eventkit   # compile bin/eventkit-cal
npm run smoke:calendar   # time calendars + week event list (default 2026-07-27β†’2026-08-03)
npm start                # stdio server (stderr: [macos-mcp] ready; N tools; macOS only)

Test a tool via MCP client or send JSON-RPC to stdin.

License

MIT

Available Tools

40 tools
calendar_create_eventC

Create a calendar event.

Inputs: end (required), start (required), summary (required), calendar (required), +4 more.

calendar_delete_eventC

Delete an event by uid.

Inputs: uid (required), calendar.

calendar_get_eventC

Get full event by uid.

Inputs: uid (required), calendar.

calendar_list_calendarsA

List Calendar.app calendars with writable flag.

Inputs: no named parameters.

calendar_list_eventsC

List events in a date range (ISO 8601 start/end).

Inputs: end (required), start (required), calendar.

calendar_search_eventsC

Search events by substring in title or location.

Inputs: query (required), end, start, calendar.

calendar_update_eventC

Update event fields by uid.

Inputs: uid (required), end, notes, start, +3 more.

contacts_createC

Create a new contact with basic fields.

Inputs: email, phone, last_name, first_name, +1 more.

contacts_deleteB

Delete a contact by Contacts.app person id.

Inputs: contact_id (required).

contacts_getB

Get full contact card by id or name.

Inputs: name, contact_id.

contacts_import_csvA

Import contacts from a Google Contacts CSV export. Upserts by email, optionally removes name-only duplicates.

Inputs: csv_path (required), dedupe, organization.

contacts_listC

List contacts. Optionally return only contacts missing an email address.

Inputs: limit, missing_email.

contacts_updateC

Update contact fields by contact_id.

Inputs: contact_id (required), email, phone, last_name, +2 more.

mail_archive_messagesB

Archive messages by id (Gmail: move to All Mail / remove from Inbox).

Inputs: message_ids (required).

mail_draft_emailA

Open a draft in Mail.app (never sends). Appends signature from signatures/ when sender is set. Em dashes are stripped from subject/body.

Inputs: to (required), cc, bcc, body, +4 more.

mail_draft_replyA

Open a reply draft in Mail.app for an existing message (never sends). Keeps Mail native rich-text quote. With body: pastes your text at the top via clipboard (requires Accessibility for Cursor).

Inputs: message_id (required), body, sender, reply_all, +2 more.

mail_get_messageC

Fetch full message content by Mail message id.

Inputs: message_id (required).

mail_list_accountsA

List Mail.app accounts configured on this Mac (name + email addresses).

Inputs: no named parameters.

mail_list_mailboxesB

List mailboxes. Optionally filter by Mail account name.

Inputs: account.

mail_list_messagesC

List recent messages from a mailbox (default INBOX). Returns Mail message ids for follow-up actions.

Inputs: limit, account, mailbox, unread_only.

mail_mark_readC

Mark messages read or unread by id.

Inputs: message_ids (required), read.

mail_move_messagesC

Move messages to another mailbox.

Inputs: mailbox (required), message_ids (required), account.

mail_save_attachmentsC

Save all attachments from a Mail message to a local directory.

Inputs: message_id (required), output_dir (required).

mail_search_messagesB

Search messages by substring in subject or sender within a mailbox.

Inputs: query (required), limit, account, mailbox, +1 more.

mail_trash_messagesC

Move messages to Trash by id.

Inputs: message_ids (required).

messages_get_threadA

Read iMessage/SMS thread by phone substring or email. Requires Full Disk Access for chat.db.

Inputs: handle (required).

messages_list_chatsC

List recent chat identifiers from Messages.app.

Inputs: limit.

notes_appendC

Append text to an existing note.

Inputs: text (required), name, folder, note_id.

notes_createC

Create a note in a folder (may require macOS automation permission).

Inputs: name (required), folder (required), body.

notes_getC

Get note title and body by id or name.

Inputs: name, folder, note_id.

notes_listC

List notes, optionally filtered by folder.

Inputs: limit, folder.

notes_list_foldersB

List Notes.app folders.

Inputs: no named parameters.

reminders_completeC

Mark a reminder complete by id or name+list.

Inputs: list, name, reminder_id.

reminders_createC

Create a reminder in a list.

Inputs: list (required), name (required), due, notes, +1 more.

reminders_deleteB

Delete a reminder by id or name+list.

Inputs: list, name, reminder_id.

reminders_listC

List reminders in a list with optional filters.

Inputs: list (required), completed, due_after, due_before.

reminders_list_listsA

List all Reminders lists.

Inputs: no named parameters.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3/5.0

    Scored across 40 tools

    Disambiguation5/5

    Each tool has a distinct domain prefix (calendar_, contacts_, mail_, etc.) and a specific action, making it impossible to confuse tools across domains. Even within a domain like mail, tools like mail_draft_email and mail_draft_reply are clearly differentiated.

    Naming Consistency5/5

    All tools follow a strict verb_noun pattern with snake_case, e.g., calendar_create_event, mail_list_messages, notes_append. The naming is uniform and predictable across all domains.

    Tool Count3/5

    40 tools is on the high side, but the server covers multiple macOS apps (Calendar, Contacts, Mail, Messages, Notes, Reminders), each requiring several operations. While the count is heavy, it is not excessive for such a broad scope, though it may overwhelm agents.

    Completeness3/5

    Most domains have CRUD-like coverage, but notable gaps exist: Mail lacks a 'send' tool (only draft), Messages cannot send new messages, Notes lacks delete and update (only append), and Reminders lacks field updates. These omissions may hinder agent workflows.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      A read-only MCP server that exposes data from native macOS apps (Mail, Notes, Calendar, Reminders, Contacts, Messages, Spotlight) to AI agents over stdio, currently in early development with no domain tools wired yet.
      7 npm
      5
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      A collection of MCP servers for Apple macOS apps (Mail, Contacts, Notes, Memory, Messages, Calendar, Reminders) enabling AI assistants to read, search, create, and update data via JXA, SQLite, and EventKit.
      28 npm
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      An MCP server that drives macOS Mail: read, search, send, organise.
      MIT