mac_messages_mcp MCP server

An MCP server that securely interfaces with your iMessage database via the Model Context Protocol (MCP), allowing LLMs to query and analyze iMessage conversations. It includes robust phone number validation, attachment processing, contact management, group chat handling, and full support for sending and receiving messages.

What mac_messages_mcp does

Summarised from the project README; check the repository for the latest details.

Tools exposed (18)

• tool_get_recent_messages – Read recent messages, filtered by contact, group chat ID, date range, or unread state; page with `limit`/`offset`
• tool_fuzzy_search_messages – Search message bodies by approximate text match, scoped to a contact or chat; defaults to 30 days, or `hours=0`
• tool_list_conversations – List every conversation with kind, message count, unread count, and last activity
• tool_wait_for_new_messages – Block until a message newer than a ROWID cursor arrives, or the timeout expires
• tool_find_contact – Fuzzy-match a name in Contacts and return phone numbers
• tool_get_chats – List named group chats and their identifiers
• tool_search_attachments – Find attachment metadata by date, contact, MIME type, and limit
• tool_search_attachment_contents – Search inside attachment text/PDF contents by date, contact, and MIME type
• tool_get_attachment – Fetch one attachment by ID, inline when supported or as a local path
• tool_check_imessage_availability – Check likely iMessage availability for a phone number or email
• tool_check_db_access – Diagnose access to `~/Library/Messages/chat.db`
• tool_check_contacts – Return a contact count and a small sample
• tool_check_addressbook – Diagnose Contacts/AddressBook database access
• tool_send_message – Send one direct or group message through Messages.app, optionally with file attachments and elicitation approval
• tool_create_contact – Create one Contacts.app entry with a phone number
• tool_schedule_message – Queue a message for later delivery while this server process runs
• tool_list_scheduled_messages – List the in-process scheduled-message queue and its status
• tool_cancel_scheduled_message – Cancel one pending scheduled message

Requirements

• Python with uv (runs with uvx/uv)

How to install mac_messages_mcp MCP in Claude Desktop, Cursor and VS Code

claude mcp add --transport stdio mac-messages-mcp -- 'uvx mac-messages-mcp'

{
  "mcpServers": {
    "mac-messages-mcp": {
      "command": "uvx mac-messages-mcp"
    }
  }
}

{
  "mcpServers": {
    "mac-messages-mcp": {
      "command": "uvx mac-messages-mcp"
    }
  }
}

{
  "servers": {
    "mac-messages-mcp": {
      "type": "stdio",
      "command": "uvx mac-messages-mcp"
    }
  }
}

Add to config generator – combine it with other servers, or get the Windsurf format.

Listed on Socketlist – add this badge to your README:

Badge markdown[](https://socketlist.pages.dev/s/carterlasalle-mac-messages-mcp/)

Maintain this project? Get it featured for free during launch →

Compare with codebase-memory-mcp →

Related Databases MCP servers