Mac Messages MCP

Read, search, and send macOS Messages from any local MCP client.

Quick start · Available tools · Agent skill · Command-line interface · Security · Changelog

Use Claude, Codex, Cursor, VS Code, or any local MCP client to search, read, and send messages through the macOS Messages app.

Mac Messages MCP runs locally on your Mac. It opens the Messages and Contacts databases read-only, returns only the data a client asks for, and uses Messages.app automation only when the client explicitly calls the send tool.

[!IMPORTANT] This server is macOS-only. Reading messages requires Full Disk Access. Sending requires a Mac signed into Messages plus permission for the launching app to automate Messages.

How it works

flowchart LR
    A[MCP client] -->|stdio| B[mac-messages-mcp]
    B --> C{Tool call}
    C -->|read tools| D[(chat.db read-only)]
    C -->|read tools| E[(AddressBook read-only)]
    C -->|send tools| F[Messages.app]
    F --> G[Recipient]
    D --> H[Untrusted-output boundary]
    E --> H
    H --> A

Everything the client reads comes from the local SQLite databases, opened read-only. Everything that leaves the machine goes out through Messages.app, under an explicit send tool call. Message- and contact-derived text is fenced as untrusted data on the way back to the model.

Capabilities

Area	What Mac Messages MCP provides
Reading	Recent messages across all conversations or filtered by contact, group chat, date range, or unread state; paging with limit/offset and forward-cursor reads
Conversations	Every conversation (1:1, business, and group) with kind, message and unread counts, last activity, and a blocking wait for new messages
Search	Fuzzy message-body search across a time window or all history, scoped to a contact or conversation
Context	Per-message service (iMessage/SMS/RCS), unread and delivery state, tapbacks, and threaded replies
Contacts	Fuzzy contact lookup by approximate name, send-ready phone numbers, and contact creation
Group chats	Named group chat discovery with stable chat IDs reused for reads and sends
Sending	iMessage with SMS/RCS fallback, file attachments, optional human approval through MCP elicitation, and iMessage reachability checks
Scheduling	Queue a message for later delivery while the server process stays alive
Attachments	Metadata search, best-effort text/PDF content search, inline images (HEIC converted to PNG), and local paths for larger or non-image files
Diagnostics	Messages and Contacts database permission checks from inside the MCP client
Privacy	Read-only SQLite access, no message archive of its own, and a structural untrusted-output boundary

Quick start

1. Install uv

brew install uv

Confirm that the launcher is available:

uvx --version

Python 3.10 or newer is required. uvx can provision a compatible Python and installs Mac Messages MCP in an isolated environment, so you do not need to create a virtual environment first.

2. Grant macOS permissions

Open System Settings → Privacy & Security → Full Disk Access and enable the app that will launch the MCP server: