messages-mcp

MCP server for reading and responding to local macOS Messages from clients like Claude Desktop and Codex.

The server reads ~/Library/Messages/chat.db, resolves names through local Contacts/AddressBook source databases, and sends through the macOS Messages app using AppleScript.

Requirements

macOS with Messages configured
Python 3.10+
Full Disk Access for the app running the MCP server
Automation permission for controlling Messages when sending

Install

From this repo:

python3 -m venv .venv
. .venv/bin/activate
pip install -e .

Run manually:

messages-mcp

Claude Desktop

Add this to Claude Desktop's MCP config, adjusting the path:

{
  "mcpServers": {
    "messages": {
      "command": "/Users/YOU/Documents/messages-mcp/.venv/bin/messages-mcp"
    }
  }
}

Restart Claude Desktop after editing the config.

Codex

Use the command path from the virtualenv:

{
  "mcpServers": {
    "messages": {
      "command": "/Users/YOU/Documents/messages-mcp/.venv/bin/messages-mcp"
    }
  }
}

Tools

list_chats(query="", limit=25) List recent chats, optionally filtered by contact name, phone/email, or group name.
get_conversation_context(chat, limit=30) Return recent messages and attachment metadata for a chat. chat can be a contact name, phone/email, or group name.
get_unread_messages(chat="", limit=20) Return unread incoming messages for one chat or all recent chats.
send_message(chat, text, dry_run=true) Send a message through Messages. dry_run defaults to true; pass false to actually send.
mark_read(chat) Best-effort mark a chat as read through Messages.

Safety

Sending is intentionally explicit. The send_message tool defaults to dry_run=true, so clients can inspect the target and text before sending.

Do not run this server for an MCP client you do not trust. Any connected client with tool access can read local Messages context and, if it calls send_message(..., dry_run=false), send messages through your account.

Troubleshooting

If chats do not appear:

Give the MCP host app Full Disk Access.
Use a contact name for one-on-one chats.
Use the exact group chat title for group chats.
Make sure Messages is signed in and synced locally.

If sending fails:

Open Messages once manually.
Approve the Automation permission prompt.
Try send_message(..., dry_run=true) first to verify the resolved target.