iMessage Max MCP Server

iMessage Max

A high-performance MCP (Model Context Protocol) server for iMessage that lets AI assistants read, search, and send your messages with proper contact resolution.

Built in Swift for native macOS integration - single binary, no runtime dependencies.

Features

• 12 Intent-Aligned Tools - Work the way you naturally ask questions, not raw database queries
• Contact Resolution - See names instead of phone numbers via macOS Contacts
• Smart Image Handling - Efficient image variants (vision/thumb/full) to avoid token bloat
• Session Grouping - Messages grouped into conversation sessions with gap detection
• Attachment Tracking - Know which images are available locally vs offloaded to iCloud
• Native Performance - Swift with raw SQLite3, Core Image GPU acceleration
• Read-Only Safe - Only reads from chat.db, send requires explicit permission

Why This Exists

Most iMessage tools expose raw database structures, requiring 3-5 tool calls per user intent. This MCP provides intent-aligned tools:

"What did Nick and I talk about yesterday?"
→ find_chat(participants=["Nick"]) + get_messages(since="yesterday")

"Show me photos from the group chat"
→ list_attachments(chat_id="chat123", type="image")

"Find where we discussed the trip"
→ search(query="trip")

Installation

Homebrew (Recommended)

brew tap cyberpapiii/tap
brew install imessage-max

From Source

git clone https://github.com/cyberpapiii/imessage-max.git
cd imessage-max/swift
swift build -c release

# Binary is at .build/release/imessage-max

Stable Dev Install Workflow

For local development, use the built-in make workflow in swift/ instead of manually rebuilding and re-granting permissions:

cd swift
make setup-signing   # one-time: create persistent signing identity
make install         # build, sign, restart launchd service, verify health

Why this matters:

• it signs the binary with a persistent local identity so Full Disk Access can persist across rebuilds
• it replaces the release binary in place
• it restarts the launchd-managed local.imessage-max service on port 8080
• it verifies the service is healthy after install

Useful commands:

cd swift
make status   # show process, signature, version, health
make restart  # restart the launchd service
make logs     # tail the stderr log
make clean    # remove debug artifacts and clear logs

Setup

1. Grant Full Disk Access

Required to read ~/Library/Messages/chat.db:

1. Open System Settings → Privacy & Security → Full Disk Access
2. Click + to add the binary

For Homebrew installs: The binary is at /opt/homebrew/Cellar/imessage-max/VERSION/bin/imessage-max (not the symlink at /opt/homebrew/bin/). Find it with:

# Open the folder containing the actual binary
open $(dirname $(readlink -f $(which imessage-max)))

For source builds: Add .build/release/imessage-max from your clone directory.

Tip: In the file picker, press ⌘+Shift+G and paste the path to navigate directly.

2. Grant Contacts Access

Required for resolving phone numbers to names. The app will request access on first run, or add manually:

System Settings → Privacy & Security → Contacts → add imessage-max

3. Configure Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

For Homebrew:

{
  "mcpServers": {
    "imessage": {
      "command": "/opt/homebrew/Cellar/imessage-max/VERSION/bin/imessage-max"
    }
  }
}

For source builds:

{
  "mcpServers": {
    "imessage": {
      "command": "/path/to/imessage-max/swift/.build/release/imessage-max"
    }
  }
}

4. Restart Claude Desktop

The MCP should now appear in Claude's tools. You can verify with the diagnose tool.

Launchd Service

If you are running iMessage Max as a background HTTP service, the intended development path is the launchd-managed binary at:

~/Library/LaunchAgents/local.imessage-max.plist

That plist should point at:

/Users/YOU/.../imessage-max/swift/.build/release/imessage-max --http --port 8080

The make install workflow updates that binary in place and restarts the service cleanly.

Tools

find_chat

Find chats by participants, name, or recent content.

find_chat(participants=["Nick"])           # Find DM with Nick
find_chat(participants=["Nick", "Andrew"]) # Find group with both
find_chat(name="Family")                   # Find by chat name
find_chat(contains_recent="dinner plans")  # Find by recent content

get_messages

Retrieve messages with flexible filtering. Returns metadata for media.

get_messages(chat_id="chat123", limit=50)      # Recent messages
get_messages(chat_id="chat123", since="24h")   # Last 24 hours
get_messages(chat_id="chat123", from_person="Nick")  # From spe