mac_messages_mcp

Overview

The mac_messages_mcp provides comprehensive access to macOS Messages database through MCP protocol. It features smart message sending that automatically routes between iMessage and SMS/RCS based on recipient capabilities, advanced message filtering by contacts and group chats, fuzzy search functionality, and progressive attachment handling to efficiently manage media files. The server implements robust security with proper macOS permissions handling and includes extensive integration options for Claude Desktop, Cursor, and Docker environments.

Try asking AI

After installing, here are 5 things you can ask your AI assistant:

• tool_get_recent_messages

  Reads recent messages from the macOS Messages app

  Try:Show me my recent messagesTry:What messages have I received in the last 24 hours?
• tool_fuzzy_search_messages

  Searches through message content with intelligent matching

  Try:Find messages about our dinner plansTry:Search for photos from last vacation
• tool_send_message

  Sends a message via iMessage or SMS/RCS based on recipient availability

  Try:Send a message to +1234567890Try:Tell John I'll be there in 15 minutes
• tool_find_contact

  Finds contacts and returns phone numbers in E.164 format

  Try:Find John's phone numberTry:Get Sarah's contact info
• tool_get_chats

  Retrieves list of chats for filtering conversations

  Try:List all my group chatsTry:Show me conversations with Sarah
• tool_check_imessage_availability

  Checks if a recipient has iMessage before sending

  Try:Can I send iMessage to this number?Try:Is +1234567890 an iPhone user?
• tool_search_attachments

  Searches for attachments by date, contact, and MIME type

  Try:Find all images Elizabeth sent in AprilTry:Search for PDF attachments in our conversation
• tool_get_attachment

  Retrieves an attachment file by its ID

  Try:Get attachment ID 42Try:Show me the photo from John's message

Comparable tools

Installation

uv pip install mac-messages-mcp

{
    "mcpServers": {
        "messages": {
            "command": "uvx",
            "args": [
                "mac-messages-mcp"
            ]
        }
    }
}

FAQ

Does this work with Android users?

Yes, the server automatically falls back to SMS/RCS when communicating with Android users who don't have iMessage.

How are attachments handled?

The server uses progressive disclosure - discovery of attachments is cheap through message search, while fetching is deliberate and supports various MIME types with special handling for images (HEIC converted to PNG).

Compare mac_messages_mcp with