# 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:

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

Run manually:

```sh
messages-mcp
```

## Claude Desktop

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

```json
{
  "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:

```json
{
  "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.