imessage-mcp

An MCP (Model Context Protocol) server that exposes Apple iMessage as tools for AI assistants — read conversations, search messages, and send iMessages directly from Claude.

Requirements

Requirement	Notes
macOS	Uses chat.db and AppleScript — no Linux/Windows support
Python 3.9+	Standard library + mcp package
Messages app	Must be open and signed in for sending messages
Full Disk Access	Required to read chat.db (see Permissions below)

Quick setup

git clone https://github.com/<your-username>/imessage-mcp
cd imessage-mcp
./setup.sh

The setup script will:

• Verify all prerequisites (macOS, Python version, chat.db access)
• Create a .venv and install dependencies
• Print the exact config snippet to add to Claude Desktop or Claude Code

Manual setup

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

Connecting to Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "imessage": {
      "command": "/path/to/imessage-mcp/.venv/bin/imessage-mcp"
    }
  }
}

Restart Claude Desktop after saving.

Connecting to Claude Code (CLI)

claude mcp add imessage /path/to/imessage-mcp/.venv/bin/imessage-mcp

Permissions

Two macOS permissions are required:

1. Full Disk Access

chat.db is protected by macOS privacy controls. Grant Full Disk Access to:

• Your terminal app (Terminal, iTerm2, Ghostty, etc.)
• Claude Desktop (if using the desktop app)

System Settings → Privacy & Security → Full Disk Access → click +

2. Automation (AppleScript)

The send_imessage tool drives the Messages app via AppleScript. macOS will show a permission prompt the first time — click Allow. If you previously denied it:

System Settings → Privacy & Security → Automation → enable Messages for your terminal / Claude

Available tools

Tool	Description
send_imessage	Send an iMessage or SMS to a phone number or Apple ID
list_imessage_conversations	List recent conversations sorted by activity
get_imessage_messages	Fetch messages from a specific conversation
search_imessages	Full-text search across all conversations
get_unread_imessages	Return all unread incoming messages

How it works

• Reading — copies ~/Library/Messages/chat.db to a temp file before querying (the live DB is often locked by imagent)
• Sending — uses AppleScript to drive the Messages app; requires Messages to be open

License

MIT