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

Related MCP server: imessage-mcp

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

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