MCP Directory

How to add Mac Messages MCP to Windsurf

Read and send macOS iMessage/SMS from your Messages database, with attachments and contacts. Paste the config into ~/.codeium/windsurf/mcp_config.json and restart Windsurf.

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

Windsurf 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 Windsurf → Cascade → the hammer/MCP icon → Configure (or edit ~/.codeium/windsurf/mcp_config.json).
  2. 2Paste the Mac Messages MCP config below.
  3. 3Fill in placeholder secrets, then save.
  4. 4Click Refresh in the MCP panel.
  5. 5Mac Messages MCP's tools become available to Cascade.

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 Windsurf

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

Where is the Windsurf config file?

Windsurf reads MCP servers from ~/.codeium/windsurf/mcp_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 Windsurf?

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