Mac Messages MCP Server

Use Claude, Codex, Cursor, VS Code, or any local MCP client to search, read, and send messages through the macOS Messages app.

Local serverstdioPython

What is the Mac Messages MCP Server?

Use Claude, Codex, Cursor, VS Code, or any local MCP client to search, read, and send messages through the macOS Messages app.

More MCP options

Compare MCP servers by category, or browse hosted MCP servers if you prefer an endpoint over a local process.

Maintainer setup documentation.

Recorded tools

Check the linked publisher documentation and your connected client's tool list. Names and availability can vary with the server version and account permissions.

ToolWhat it does
messages//contact/{contact}/{hours}
tool_get_recent_messagesRead recent messages, filtered by contact, group chat ID, date range, or unread state; page with limit/offset
tool_fuzzy_search_messagesSearch message bodies by approximate text match, scoped to a contact or chat; defaults to 30 days, or hours=0
tool_list_conversationsList every conversation with kind, message count, unread count, and last activity
tool_wait_for_new_messagesBlock until a message newer than a ROWID cursor arrives, or the timeout expires
tool_find_contactFuzzy-match a name in Contacts and return phone numbers
tool_get_chatsList named group chats and their identifiers
tool_search_attachmentsFind attachment metadata by date, contact, MIME type, and limit
tool_search_attachment_contentsSearch inside attachment text/PDF contents by date, contact, and MIME type
tool_get_attachmentFetch one attachment by ID, inline when supported or as a local path
tool_check_imessage_availabilityCheck likely iMessage availability for a phone number or email
tool_check_db_accessDiagnose access to ~/Library/Messages/chat.db
tool_check_contactsReturn a contact count and a small sample
tool_check_addressbookDiagnose Contacts/AddressBook database access
tool_send_messageSend one direct or group message through Messages.app, optionally with file attachments and elicitation approval
tool_create_contactCreate one Contacts.app entry with a phone number
tool_schedule_messageQueue a message for later delivery while this server process runs
tool_list_scheduled_messagesList the in-process scheduled-message queue and its status
tool_cancel_scheduled_messageCancel one pending scheduled message

How to install the Mac Messages MCP Server

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

From the project documentation. Replace placeholders and example paths before connecting.

Example prompts to try

  • “Use Mac Messages MCP to messages.”
  • “Use Mac Messages MCP to tool get recent messages.”
  • “Use Mac Messages MCP to tool fuzzy search messages.”

Frequently asked questions

Use Claude, Codex, Cursor, VS Code, or any local MCP client to search, read, and send messages through the macOS Messages app. Confirm the tools offered by your installed version in the connected client. Tool availability and permissions depend on the server and account configuration.