How to add Mac Messages MCP to Claude Desktop

Read and send macOS iMessage/SMS from your Messages database, with attachments and contacts. Paste the config into ~/Library/Application Support/Claude/claude_desktop_config.json and restart Claude Desktop.

Last updated June 14, 2026 · 297★ · stdio · no auth

Claude Desktop config for Mac Messages MCP

uv pip install mac-messages-mcp

{
  "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.

Setup steps

1Open Claude Desktop → Settings → Developer → Edit Config (this opens ~/Library/Application Support/Claude/claude_desktop_config.json).
2Paste the Mac Messages MCP config below under the top-level "mcpServers" key.
3Fill in any placeholder secrets (API keys, paths) in the snippet.
4Save the file, then fully quit and reopen Claude Desktop.
5Open a chat and confirm Mac Messages MCP's tools appear under the 🔌 tools menu.

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

What Mac Messages MCP can do in Claude Desktop

tool_get_recent_messages

Read 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_message

Send a message to a recipient, automatically choosing iMessage or SMS/RCS based on availability.

tool_find_contact

Find a contact by name, phone number, or email and return send-ready phone matches.

tool_check_db_access

Check whether the server can access the local Messages database (diagnostic).

tool_check_contacts

Check access to the contacts/address book (diagnostic).

tool_check_addressbook

Check access to the macOS Address Book (diagnostic).

tool_get_chats

List group chats and their chat IDs for use with tool_get_recent_messages.

tool_check_imessage_availability

Check whether a recipient (phone number or email) appears reachable through iMessage, indicating likely SMS/RCS fallback otherwise (read-only).

Security

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 + Claude Desktop FAQ

Where is the Claude Desktop config file?

Claude Desktop reads MCP servers from ~/Library/Application Support/Claude/claude_desktop_config.json. Paste the Mac Messages MCP config there under the "mcpServers" key and restart the client.

Is Mac Messages MCP safe to use with Claude Desktop?

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.

View repo Full Mac Messages MCP page