macos-mcp
A local MCP server for reading and managing macOS native apps (Mail, Calendar, Reminders, Notes, Messages, Contacts) directly from an MCP client, with no cloud credentials or network calls.
π§ Mail: List accounts, mailboxes, messages; search messages (by subject/sender, filter unread); get full content; save attachments; draft emails and replies (never sends) with CC/BCC, signatures; archive, trash, mark read/unread, move messages.
π Calendar: List calendars, events (date range); search events; get details; create, update, delete events (supports attendees, alarms, location, notes).
β Reminders: List lists, reminders (filter completed/due); search reminders; create reminders (with due date, notes, priority); mark complete; delete.
π Notes: List folders, notes; search notes; get note body; create notes; append text to existing notes.
π¬ Messages: Read iMessage/SMS threads by phone/email; list recent chats. Requires Full Disk Access.
π€ Contacts: List contacts (optionally filter missing email); search; get full card; create, update, delete; import Google Contacts CSV (upsert by email, deduplication).
Key Features & Limitations:
Operates locally on macOS only (no Windows/Linux).
Mail is draft-only; emails are never sent automatically.
Uses AppleScript/JXA (EventKit for Calendar reads).
Requires macOS Privacy & Security permissions (Calendars, Automation, Full Disk Access for Messages).
No cloud integrations (Gmail API, OAuth, etc.).
Provides tools to interact with macOS native apps: Mail, Calendar, Reminders, Notes, Messages, and Contacts, allowing AI agents to read, search, create, update, and delete data in these apps via AppleScript/JXA.
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., "@macos-mcp Show my upcoming events for today"
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.
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.app |
| |
Calendar | Calendar.app |
|
Reminders | Reminders.app |
|
Notes | Notes.app |
|
Messages | Messages.app ( |
|
Contacts | Contacts.app |
|
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.jsRestart 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.shEdit 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 |
|
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 ( |
On first calendar read, macOS may prompt for Calendar access. If the helper exits with βCalendar Full Access requiredβ:
Open System Settings β Privacy & Security β Calendars
Find Cursor (MCP) and/or Terminal (CLI smoke tests)
Enable Full Access (not Write Only / Add Only)
Re-run
npm run smoke:calendaror 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 |
| List Mail accounts |
| List mailboxes (optional account filter) |
| List messages in mailbox |
| Search subject/sender |
| Full message by id |
| Save message attachments to a local directory |
| Open new compose draft (never sends) |
| Open reply draft in thread (never sends) |
| Move to All Mail |
| Move to Trash |
| Mark read/unread |
| Move to mailbox |
Calendar (calendar_*)
Tool | Description |
| List calendars |
| Events in date range |
| Search title/location |
| Full event |
| Create event (optional |
| Update event |
| Delete event |
Reminders (reminders_*)
Tool | Description |
| List reminder lists |
| List reminders in a list |
| Search name/notes |
| Create reminder |
| Mark complete |
| Delete reminder |
Notes (notes_*)
Tool | Description |
| List folders |
| List notes |
| Search title/body |
| Get note body |
| Create note |
| 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 |
| Thread by phone/email substring |
| Recent chats |
Requires Full Disk Access. Reads iMessage/SMS locally; no network.
Contacts (contacts_*)
Tool | Description |
| List contacts (optional: missing email only) |
| Search by name/email/phone |
| Full contact card |
| Create contact |
| Update contact |
| Delete contact |
| 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; genericrunJxa(appName, body, args).AppleScript:
mail_draft_email, calendar create/update/delete/get, and contacts create/update (JXAmakeis 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 toolscalendar_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_searchA
Search Contacts by name, email, or phone substring.
Inputs: query (required).
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.
notes_searchB
Search notes by substring in title or body.
Inputs: query (required), folder.
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.
reminders_searchC
Search reminders by substring in name or notes.
Inputs: query (required), list.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelogβ¦
TDQS
Scored across 40 tools
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.
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.
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.
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
Related MCP Connectors
MCP connector for iMessage & Contacts via a local Mac agent + Vercel relay
Your IMAP mailbox as an MCP server: read, search and (if you allow it) organize mail. Open source.
Read, search and manage iCloud Mail, Calendar and Contacts from Claude and other MCP clients.
Search, read, and write your Apple Notes from ChatGPT/Claude via a local Mac agent + MCP relay.
Related MCP Servers
- AlicenseBqualityCmaintenanceMCP server for macOS Apple apps. Enables read/write access to Notes, Reminders, Calendar, Contacts, and Safari using SQLite and JXA, all running locally.2811 npm4MIT
- AlicenseNot gradedqualityDmaintenanceA 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 npm5MIT
- AlicenseNot gradedqualityBmaintenanceA 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 npmMIT
- AlicenseNot gradedqualityBmaintenanceAn MCP server that drives macOS Mail: read, search, send, organise.MIT