A collection of Model Context Protocol (MCP) servers that provide AI assistants with access to native Apple applications on macOS. - macOS (uses AppleScript and macOS-specific APIs) - Node.js 18+ (22+ for Apple Messages) - Full Disk Access granted to your terminal app (System Settings > Privacy & Security > Full Disk Access) — required for reading the Messages database - The associated Apple app m
Add this skill
npx mdskills install griches/apple-mcpComprehensive suite of seven MCP servers providing deep integration with Apple ecosystem apps
1# Apple MCP Servers23A collection of [Model Context Protocol (MCP)](https://modelcontextprotocol.io) servers that provide AI assistants with access to native Apple applications on macOS.45## Servers67| Server | Status | Description |8|--------|--------|-------------|9| [Apple Notes](#apple-notes) | Done | Read, create, update, move, and delete notes and folders |10| [Apple Messages](#apple-messages) | Done | Read message history, search conversations, and send messages |11| [Apple Contacts](#apple-contacts) | Done | Manage contacts, groups, and contact details |12| [Apple Mail](#apple-mail) | Done | Read, send, search, flag, and manage email |13| [Apple Reminders](#apple-reminders) | Done | Create, update, complete, and manage reminders and lists |14| [Apple Calendar](#apple-calendar) | Done | Create, update, and manage calendar events |15| [Apple Maps](#apple-maps) | Done | Search locations, get directions, and drop pins (visual only — limited by Apple's automation support) |1617## Requirements1819- **macOS** (uses AppleScript and macOS-specific APIs)20- **Node.js** 18+ (22+ for Apple Messages)21- **Full Disk Access** granted to your terminal app (System Settings > Privacy & Security > Full Disk Access) — required for reading the Messages database22- **The associated Apple app must be running** — each MCP server communicates with its corresponding app via AppleScript, so the app (e.g. Contacts, Mail, Notes) needs to be open for the server to function2324## Safety Modes2526All servers (except Apple Maps, which is UI-only) support two optional safety flags:2728| Mode | Flag | Behaviour |29|------|------|-----------|30| **Normal** (default) | _(none)_ | All tools available, no restrictions |31| **Read-only** | `--read-only` | Destructive/write tools are not registered at all |32| **Confirm** | `--confirm-destructive` | Destructive tools require a `confirm: true` parameter; without it they return a warning asking the AI to check with the user first |3334### Claude Desktop3536```json37{38 "mcpServers": {39 "apple-notes": {40 "command": "npx",41 "args": ["@griches/apple-notes-mcp", "--read-only"]42 },43 "apple-messages": {44 "command": "npx",45 "args": ["@griches/apple-messages-mcp", "--confirm-destructive"]46 }47 }48}49```5051### Claude Code5253```bash54claude mcp add apple-notes -- npx @griches/apple-notes-mcp --read-only55claude mcp add apple-messages -- npx @griches/apple-messages-mcp --confirm-destructive56```5758### Destructive tools by server5960| Server | Destructive tools |61|--------|-------------------|62| Notes | `delete_note`, `delete_folder` |63| Contacts | `delete_contact`, `delete_group` |64| Reminders | `delete_reminder`, `delete_list` |65| Calendar | `delete_event` |6667## Quick Start6869No cloning or building required — install and run directly with `npx`:7071```bash72# Apple Notes73npx @griches/apple-notes-mcp7475# Apple Messages76npx @griches/apple-messages-mcp7778# Apple Contacts79npx @griches/apple-contacts-mcp8081# Apple Reminders82npx @griches/apple-reminders-mcp8384# Apple Calendar85npx @griches/apple-calendar-mcp8687# Apple Maps88npx @griches/apple-maps-mcp8990# Apple Mail91npx @griches/apple-mail-mcp92```9394### Claude Code9596```bash97claude mcp add apple-notes -- npx @griches/apple-notes-mcp98claude mcp add apple-messages -- npx @griches/apple-messages-mcp99claude mcp add apple-contacts -- npx @griches/apple-contacts-mcp100claude mcp add apple-reminders -- npx @griches/apple-reminders-mcp101claude mcp add apple-calendar -- npx @griches/apple-calendar-mcp102claude mcp add apple-maps -- npx @griches/apple-maps-mcp103claude mcp add apple-mail -- npx @griches/apple-mail-mcp104```105106### Claude Desktop107108Add to your `claude_desktop_config.json`:109110```json111{112 "mcpServers": {113 "apple-notes": {114 "command": "npx",115 "args": ["@griches/apple-notes-mcp"]116 },117 "apple-messages": {118 "command": "npx",119 "args": ["@griches/apple-messages-mcp"]120 },121 "apple-contacts": {122 "command": "npx",123 "args": ["@griches/apple-contacts-mcp"]124 },125 "apple-reminders": {126 "command": "npx",127 "args": ["@griches/apple-reminders-mcp"]128 },129 "apple-calendar": {130 "command": "npx",131 "args": ["@griches/apple-calendar-mcp"]132 },133 "apple-maps": {134 "command": "npx",135 "args": ["@griches/apple-maps-mcp"]136 },137 "apple-mail": {138 "command": "npx",139 "args": ["@griches/apple-mail-mcp"]140 }141 }142}143```144145## Install from Source146147If you prefer to build from source:148149```bash150git clone https://github.com/griches/apple-mcp.git151cd apple-mcp152153# Apple Notes154cd notes && npm install && npm run build155156# Apple Messages157cd ../messages && npm install && npm run build158159# Apple Contacts160cd ../contacts && npm install && npm run build161162# Apple Reminders163cd ../reminders && npm install && npm run build164165# Apple Calendar166cd ../calendar && npm install && npm run build167168# Apple Maps169cd ../maps && npm install && npm run build170171# Apple Mail172cd ../mail && npm install && npm run build173```174175Then configure your MCP client to run the built files directly:176177```json178{179 "mcpServers": {180 "apple-notes": {181 "command": "node",182 "args": ["/absolute/path/to/notes/build/index.js"]183 },184 "apple-messages": {185 "command": "node",186 "args": ["/absolute/path/to/messages/build/index.js"]187 },188 "apple-contacts": {189 "command": "node",190 "args": ["/absolute/path/to/contacts/build/index.js"]191 },192 "apple-reminders": {193 "command": "node",194 "args": ["/absolute/path/to/reminders/build/index.js"]195 },196 "apple-calendar": {197 "command": "node",198 "args": ["/absolute/path/to/calendar/build/index.js"]199 },200 "apple-maps": {201 "command": "node",202 "args": ["/absolute/path/to/maps/build/index.js"]203 },204 "apple-mail": {205 "command": "node",206 "args": ["/absolute/path/to/mail/build/index.js"]207 }208 }209}210```211212---213214## Apple Notes215216An MCP server that interacts with Apple Notes via AppleScript.217218### Tools219220| Tool | Description |221|------|-------------|222| `list_folders` | List all folders in Apple Notes |223| `create_folder` | Create a new folder |224| `list_notes` | List all notes in a folder |225| `get_note` | Get the full content of a note by title |226| `create_note` | Create a new note (HTML body) in a folder |227| `update_note` | Update the body of an existing note |228| `move_note` | Move a note from one folder to another |229| `append_to_note` | Append HTML content to an existing note |230| `delete_note` | Delete a note |231| `delete_folder` | Delete a folder and all its notes |232| `search_notes` | Search notes by keyword in titles and body content |233234### Usage Examples235236- "List my Apple Notes folders"237- "Get my Shopping note"238- "Create a note called Meeting Notes in my Work folder"239- "Search my notes for recipes"240241---242243## Apple Messages244245An MCP server that reads messages from the macOS Messages database (SQLite) and sends messages via AppleScript.246247### Tools248249| Tool | Description |250|------|-------------|251| `list_chats` | List recent chats with last message preview |252| `get_chat_messages` | Get message history for a specific chat (with optional date range filtering) |253| `search_messages` | Search messages by text content |254| `send_message` | Send an iMessage or SMS |255| `get_chat_participants` | Get participants of a chat |256257### Permissions258259- **Reading messages**: Requires Full Disk Access for your terminal app to read `~/Library/Messages/chat.db`260- **Sending messages**: macOS will prompt you to allow your terminal app to control the Messages app via AppleScript261262### Usage Examples263264- "Show my recent messages"265- "Search my messages for flight confirmation"266- "Send a message to +1234567890 saying I'm on my way"267268---269270## Apple Contacts271272An MCP server that interacts with Apple Contacts via AppleScript.273274### Tools275276| Tool | Description |277|------|-------------|278| `list_groups` | List all groups in Apple Contacts |279| `list_contacts` | List all contacts, optionally filtered by group |280| `get_contact` | Get full details of a contact (emails, phones, addresses, etc.) |281| `search_contacts` | Search contacts by name |282| `create_contact` | Create a new contact with optional email, phone, organization |283| `update_contact` | Update an existing contact's details |284| `delete_contact` | Delete a contact by name |285| `create_group` | Create a new group |286| `delete_group` | Delete a contact group |287| `add_contact_to_group` | Add a contact to a group |288| `remove_contact_from_group` | Remove a contact from a group |289290### Usage Examples291292- "List all my contacts"293- "Find contacts named John"294- "Get details for Jane Smith"295- "Create a contact for Bob Jones at Acme Corp"296297---298299## Apple Reminders300301An MCP server that interacts with Apple Reminders via AppleScript.302303### Tools304305| Tool | Description |306|------|-------------|307| `list_lists` | List all reminder lists |308| `create_list` | Create a new reminder list |309| `list_reminders` | List reminders in a list (optionally include completed) |310| `get_reminder` | Get full details of a reminder by name |311| `create_reminder` | Create a new reminder with optional due date, notes, and priority |312| `update_reminder` | Update an existing reminder's details |313| `complete_reminder` | Mark a reminder as completed |314| `uncomplete_reminder` | Mark a completed reminder as incomplete |315| `delete_reminder` | Delete a reminder |316| `delete_list` | Delete a reminder list and all its reminders |317| `search_reminders` | Search reminders by name across lists |318319### Usage Examples320321- "Show my reminder lists"322- "List reminders in my Shopping list"323- "Create a reminder to buy milk in my Groceries list"324- "Mark the dentist appointment reminder as done"325326---327328## Apple Calendar329330An MCP server that interacts with Apple Calendar. Read operations use a compiled Swift EventKit binary for fast access (~0.1s vs 50-140s via AppleScript). Write operations use AppleScript.331332### Permissions333334- **Calendar access**: macOS will prompt you to grant calendar access the first time a read operation is used (System Settings > Privacy & Security > Calendars)335- **Creating/deleting events**: macOS will prompt you to allow your terminal app to control the Calendar app via AppleScript336337### Tools338339| Tool | Description |340|------|-------------|341| `list_calendars` | List all calendars |342| `list_all_events` | List events across all calendars within a date range |343| `list_events` | List events in a specific calendar within a date range |344| `get_event` | Get full details of an event by summary/title |345| `create_event` | Create a new event with date, time, location, and description |346| `update_event` | Update an existing event's details |347| `delete_event` | Delete an event by summary/title |348| `search_events` | Search events by summary/title across calendars |349350### Usage Examples351352- "List my calendars"353- "Show events in my Work calendar for next week"354- "Create a meeting tomorrow at 2pm in my Work calendar"355- "Search for events about standup"356357---358359## Apple Maps360361An MCP server that interacts with Apple Maps using Maps URL schemes.362363> **Note:** Apple Maps has a very limited AppleScript/automation dictionary compared to other Apple apps. There is no supported way to programmatically read back search results, route details, or location data from Maps. As a result, these tools open Apple Maps with the requested query but cannot return structured data (e.g. addresses, coordinates, distances) to the agent. The results are visual — you'll see them in the Maps app.364365### Tools366367| Tool | Description |368|------|-------------|369| `search_location` | Search for a location in Apple Maps |370| `get_directions` | Get directions between two locations (driving, walking, or transit) |371| `drop_pin` | Drop a pin at specific coordinates |372| `open_address` | Open a specific address in Apple Maps |373| `save_to_favorites` | Open a location in Maps so you can save it as a favorite |374375### Usage Examples376377- "Search for coffee shops near Times Square"378- "Get walking directions from Central Park to the Met"379- "Show me 1 Apple Park Way, Cupertino on a map"380- "Drop a pin at 48.8584, 2.2945"381382---383384## Apple Mail385386An MCP server that interacts with Apple Mail via AppleScript.387388### Tools389390| Tool | Description |391|------|-------------|392| `list_mailboxes` | List all mailboxes across accounts with unread counts |393| `list_messages` | List recent messages in a mailbox |394| `get_message` | Get the full content of an email by ID |395| `search_messages` | Search emails by subject or sender across mailboxes |396| `send_email` | Send an email with optional CC/BCC (supports multiple recipients) |397| `get_unread_count` | Get unread count for a mailbox or all mailboxes |398| `move_message` | Move an email to a different mailbox |399| `mark_read` | Mark an email as read or unread |400| `delete_message` | Delete an email (moves to trash) |401| `flag_message` | Flag or unflag an email message |402403### Usage Examples404405- "How many unread emails do I have?"406- "Show my recent emails in INBOX"407- "Search my email for invoices"408- "Send an email to bob@example.com about the meeting"409410---411412## Development413414Each server is a standalone TypeScript project in its own directory.415416```bash417# Run tests for Notes418cd notes419npm test420421# Run tests for Messages422cd messages423npm test424```425426## License427428MIT429
Full transparency — inspect the skill content before installing.