MCP Directory

How to add Mac Messages MCP to Cursor

Read and send macOS iMessage/SMS from your Messages database, with attachments and contacts. Paste the config into ~/.cursor/mcp.json and restart Cursor.

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

Cursor 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

  1. 1Open Cursor → Settings → MCP → Add new MCP server (or edit ~/.cursor/mcp.json directly).
  2. 2Paste the Mac Messages MCP config below into the "mcpServers" object.
  3. 3Fill in placeholder secrets, then save.
  4. 4Cursor reloads MCP servers automatically — check Settings → MCP for a green status dot.
  5. 5Ask Cursor to use one of Mac Messages MCP's tools to confirm it's connected.

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 Cursor

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 + Cursor FAQ

Where is the Cursor config file?

Cursor reads MCP servers from ~/.cursor/mcp.json. Paste the Mac Messages MCP config there under the "mcpServers" key and restart the client.

Is Mac Messages MCP safe to use with Cursor?

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.

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