Mac Messages MCP
Read and send macOS iMessage/SMS from your Messages database, with attachments and contacts.
Add to your client
Copy the config for your MCP client and paste it into its config file.
uv pip install mac-messages-mcpPaste into ~/Library/Application Support/Claude/claude_desktop_config.json
{
"mcpServers": {
"mac-messages-mcp": {
"command": "uvx",
"args": [
"mac-messages-mcp"
]
}
}
}Requires `uv` (the Python package runner). Install it from https://docs.astral.sh/uv/ if `uvx` is not found.
Step-by-step guides: Add to Claude Desktop · Add to Cursor · Add to Windsurf
Before you start
- macOS (tested on macOS 11+)
- Python 3.10+
- uv package manager (e.g. brew install uv)
- Full Disk Access permission for your terminal or host app to read the Messages database
- Messages configured on the Mac for sending and iMessage availability checks
About Mac Messages MCP
An MCP server that securely interfaces with the macOS Messages (iMessage) database via the Model Context Protocol, allowing LLMs to query and analyze conversations and to send messages. It includes phone number validation, attachment processing, contact management, group chat handling, and iMessage/SMS delivery.
Tools & capabilities (11)
tool_get_recent_messagesRead recent macOS Messages as a plain-text summary (read-only). Filter by contact for one-to-one conversations or by chat_id for a group conversation; includes timestamps, participants, and compact attachment markers.
tool_send_messageSend a message to a recipient, automatically choosing iMessage or SMS/RCS based on availability.
tool_find_contactFind a contact by name, phone number, or email and return send-ready phone matches.
tool_check_db_accessCheck whether the server can access the local Messages database (diagnostic).
tool_check_contactsCheck access to the contacts/address book (diagnostic).
tool_check_addressbookCheck access to the macOS Address Book (diagnostic).
tool_get_chatsList group chats and their chat IDs for use with tool_get_recent_messages.
tool_check_imessage_availabilityCheck whether a recipient (phone number or email) appears reachable through iMessage, indicating likely SMS/RCS fallback otherwise (read-only).
tool_fuzzy_search_messagesFuzzy-match a search term against message bodies over a configurable time window with an adjustable threshold.
tool_search_attachmentsSearch message attachments by date range, contact, and MIME type, returning metadata only (id, MIME type, filename, size, timestamp, sender).
tool_get_attachmentFetch a single attachment by its ROWID. Image MIME types return inline (HEIC converted to PNG, capped by max_bytes); PDFs, video, and audio return a filesystem path.
What this server can do
Mac Messages MCP provides tools for these capabilities — tap one to see every MCP server that does the same:
When to use it
- Read and summarize recent iMessage/SMS conversations with a specific contact or group chat
- Send messages from an LLM agent, automatically falling back to SMS for Android recipients
- Find all images or PDFs a contact sent within a date range without scanning message text
- Check whether a recipient has iMessage before sending
- Search message history for specific text using fuzzy matching
Security notes
Accesses the local Messages database directly, which contains personal communications; use responsibly and ensure you have appropriate permissions. Requires macOS Full Disk Access for your terminal or the host app (e.g. Claude Desktop, Cursor). Run only one instance of the server at a time. The server can send messages on your behalf via iMessage/SMS.
Mac Messages MCP FAQ
Does this work inside a Linux Docker container?
No. Messages.app automation is macOS-only and will not work inside a Linux container. A Dockerfile is included only for catalog checks and read-only database experiments; for Docker access from macOS, use mcp-proxy to bridge the stdio server to HTTP.
What permission does it need?
It requires macOS Full Disk Access for your terminal app or host app (Claude Desktop/Cursor) so it can read the Messages database. Restart the app after granting access.
Can I run it on both Claude Desktop and Cursor at once?
No. Only run one instance of the MCP server at a time, not both simultaneously.
How should phone numbers be formatted?
E.164 numbers with a leading + (e.g. +14155551234) are the most reliable. Bare digit numbers with a country code are normalized, and 10-digit US numbers are sent as +1...
Alternatives to Mac Messages MCP
Compare all alternatives →
Connect your personal WhatsApp: search, read and send messages and media locally
Powerful Slack MCP with stdio/SSE/HTTP, DMs, group DMs and no-admin token auth
Full Telegram user-account MCP via MTProto: read chats, manage groups, send messages