carterlasalle/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
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
Confirm that the launcher is available:
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:
- Claude Desktop, Cursor, VS Code, or the ChatGPT desktop app when configured in
that app
- Terminal, iTerm2, Ghostty, or another terminal when using Claude Code or Codex
CLI from that terminal
Quit and reopen the app after changing Full Disk Access. On the first contact
lookup or send, macOS may separately ask for access to Contacts or permission to
control Messages. Allow those prompts.
Also make sure Messages.app is open, signed in, and already able to send a
normal message.
3. Add the server to your MCP client
The server command is the same everywhere:
Choose your client below.
Claude Desktop
Open **Claude → Settings → Developer → Edit Config**, then add:
Preserve any other servers already in claude_desktop_config.json, save the
file, and restart Claude Desktop.
Claude Desktop also supports installable .mcpb extensions. See
Build the Claude Desktop extension if you
want to package this repository as one.
Claude Code
Add it once at user scope so it is available in every project:
Verify it:
Inside Claude Code, run /mcp to inspect the connection and tools.
Codex CLI, Codex IDE extension, and ChatGPT desktop app
Codex clients on the same Mac share MCP configuration. Add the server with:
Then verify it:
You can also add it directly to ~/.codex/config.toml:
Restart the desktop app or IDE extension after changing the configuration. In
Codex CLI, use /mcp to view the active server.
Cursor
Or open **Cursor Settings → Tools & MCP → New MCP Server** and use: