apple-mcp 1.0.0

Apple apps MCP Server — control Messages, Notes, Reminders, Calendar, Contacts, and Photos through AppleScript. Fully offline, no API keys needed.

apple-mcp

Apple Apps MCP Server — control Messages, Notes, Reminders, Calendar, Contacts, and Photos through AppleScript.

macOS only — requires macOS with Automation permissions granted to your terminal / Claude Code.

27 tools across 6 Apple apps — fully offline, no API keys, no network calls. All data stays on your Mac.

Tools

Messages (5)

Tool	Description
messages_list_chats	List all conversations
messages_get_chat	Get messages from a specific conversation
messages_get_recent	Get recent messages across all chats
messages_search	Search messages by content
messages_send	Send an iMessage or SMS

Notes (5)

Tool	Description
notes_list_folders	List all Notes folders
notes_list	List notes (optionally filter by folder)
notes_get	Get the full content of a note
notes_create	Create a new note
notes_search	Search notes by content

Reminders (5)

Tool	Description
reminders_list_lists	List all Reminder lists
reminders_list	List reminders (optionally filter by list)
reminders_create	Create a reminder with optional due date
reminders_complete	Mark a reminder as complete
reminders_search	Search reminders by name

Calendar (4)

Tool	Description
calendar_list	List all calendars
calendar_today	Get today's events
calendar_events	Get events in a date range
calendar_create_event	Create a new calendar event

Contacts (4)

Tool	Description
contacts_list	List all contacts
contacts_search	Search by name, email, or phone
contacts_get	Get detailed contact information
contacts_groups	List contact groups

Photos (4)

Tool	Description
photos_list_albums	List all photo albums
photos_recent	Get recently added photos
photos_album	Get photos from a specific album
photos_search	Search photos by keyword

---

Setup

Requirements

• macOS (AppleScript is macOS-only)
• Python 3.10+
• uv package manager

Step 1 — Install

pip install apple-mcp
# or with uv:
uv add apple-mcp

Step 2 — Grant Permissions

The first time each app is accessed, macOS will prompt for Automation permission. You can also grant them upfront:

1. Open System Settings → Privacy & Security → Automation
2. Find your terminal app (Terminal, iTerm2) or Claude Code
3. Enable access for: Messages, Notes, Reminders, Calendar, Contacts, Photos

For Messages, full disk access may be needed for reading message history. Go to Privacy & Security → Full Disk Access and add your terminal app.

Step 3 — Add to Claude Code

claude mcp add apple -- uvx apple-mcp

Or manually in your Claude config (~/.claude/claude_desktop_config.json):

{
  "mcpServers": {
    "apple": {
      "command": "uvx",
      "args": ["apple-mcp"]
    }
  }
}

---

Privacy & Security

• Fully offline — no network requests, no third-party APIs
• All data stays on your Mac
• Uses AppleScript and local SQLite database (~/Library/Messages/chat.db) for Messages
• No credentials or tokens required

---

Troubleshooting

"Not authorized to send Apple events": Go to System Settings → Privacy & Security → Automation and enable the app.

Messages not showing: Ensure Full Disk Access is granted to your terminal app (System Settings → Privacy & Security → Full Disk Access).

Photos tools slow: Photos.app must be running. Large libraries may take a moment to query.

Calendar/Reminders not responding: Open the respective app once manually to ensure it initializes properly.

---

Requirements

• macOS (10.15 Catalina or later recommended)
• Python 3.10+
• Automation permissions in System Settings

License

MIT — Hitesh Gupta