Imessage Max

🚀 iMessage Max

iMessage Max is a high - performance MCP (Model Context Protocol) server for iMessage. It enables AI assistants to read, search, and send messages while accurately resolving contacts.

Built in Swift for seamless native macOS integration, it comes as a single binary with no runtime dependencies.

🚀 Quick Start

iMessage Max is a powerful MCP server for iMessage. Here's how to get it up and running:

📦 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

Setup

1. Grant Full Disk Access

To read ~/Library/Messages/chat.db, you need to grant full disk access:

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.

💡 Usage Tip

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

2. Grant Contacts Access

This is required for resolving phone numbers to names. The app will request access on first run, or you can add it 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/1.0.0/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.

✨ Features

• 12 Intent - Aligned Tools: Work in a natural way of asking questions, rather than using 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 are 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 and Core Image GPU acceleration.
• Read - Only Safe: Only reads from chat.db, and sending messages requires explicit permission.

📚 Documentation

Why This Exists

Most iMessage tools expose raw database structures, usually 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")

💻 Usage Examples

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 specific person

get_attachment

Retrieve image content by attachment ID with resolution variants.

get_attachment(attachment_id="att123")                 # Default: vision (1568px)
get_attachment(attachment_id="att123", variant="thumb") # Quick preview (400px)
get_attachment(attachment_id="att123", variant="full")  # Original resolution

list_chats

Browse recent chats with previews.

list_chats(limit=20)          # Recent chats
list_chats(is_group=True)     # Only group chats
list_chats(since="7d")        # Active in last week

search

Full - text search across messages.

search(query="dinner")                    # Search all messages
search(query="meeting", from_person="Nick")  # From specific person
search(query="party", is_group=True)      # Only in group chats

get_context

Get messages surrounding a specific message.

get_context(message_id="msg_123", before=5, after=10)

get_active_conversations

Find chats with recent back - and - forth activity.

get_active_conversations(hours=24)
get_active_conversations(is_group=True, min_exchanges=3)

list_attachments

List attachments with metadata. Includes available field showing if file is on disk.

list_attachments(type="image", since="7d")
list_attachments(chat_id="chat123", type="any")

get_unread

Get unread messages or summary.

get_unread()                  # Unread from last 7 days
get_unread(since="24h")       # Last 24 hours
get_unread(mode="summary")    # Summary by chat

send

Send a message (requires Automation permission for Messages.app).

send(to="Nick", text="Hey!")
send(chat_id="chat123", text="Running late")

diagnose

Troubleshoot configuration and permission issues.

diagnose()  # Returns: database status, contacts count, permissions

HTTP Mode

For MCP Router, MCP Inspector, or other HTTP - based integrations:

imessage-max --http --port 8080

Running as a Service (Recommended)

Create a launchd plist at ~/Library/LaunchAgents/local.imessage-max.plist:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>Label</key>
    <string>local.imessage-max</string>
    <key>ProgramArguments</key>
    <array>
        <string>/path/to/imessage-max</string>
        <string>--http</string>
        <string>--port</string>
        <string>8080</string>
    </array>
    <key>RunAtLoad</key>
    <true/>
    <key>KeepAlive</key>
    <true/>
    <key>StandardOutPath</key>
    <string>/Users/YOU/Library/Logs/imessage-max.stdout.log</string>
    <key>StandardErrorPath</key>
    <string>/Users/YOU/Library/Logs/imessage-max.stderr.log</string>
</dict>
</plist>

Then load it:

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

MCP Router Integration

Add to MCP Router as a remote - streamable server:

INSERT INTO servers (id, name, server_type, remote_url, auto_start, disabled, created_at, updated_at)
VALUES ('imessage', 'imessage', 'remote-streamable', 'http://127.0.0.1:8080', 1, 0, strftime('%s','now'), strftime('%s','now'));

Session Management

The HTTP transport supports clean reconnection:

• Each client connection gets its own isolated session.
• Sessions auto - expire after 1 hour of inactivity.
• If MCP Router disconnects, it can reconnect seamlessly with a fresh session.
• No "Server already initialized" errors on reconnection.

🔧 Technical Details

Troubleshooting

Contacts showing as phone numbers

Run diagnose to check status. If contacts_authorized is false:

• Add the imessage-max binary to System Settings → Privacy & Security → Contacts

"Database not found" error

Add the imessage-max binary to System Settings → Privacy & Security → Full Disk Access

Images show "attachment_offloaded" error

Some attachments are stored in iCloud, not on disk. The list_attachments tool shows available: true/false for each attachment. To download offloaded attachments, open the conversation in Messages.app.

MCP not loading in Claude Desktop

1. Check config file syntax is valid JSON.
2. Verify the binary path is correct.
3. Restart Claude Desktop completely (Cmd+Q).

Architecture

┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│  Claude/AI      │◄───►│  iMessage Max   │◄───►│  chat.db        │
│  Assistant      │     │  (Swift MCP)    │     │  (SQLite)       │
└─────────────────┘     └────────┬────────┘     └─────────────────┘
                                │
                                ▼
                        ┌─────────────────┐
                        │  Contacts.app   │
                        │  (CNContactStore)│
                        └─────────────────┘

Requirements

• macOS 13+ (Ventura or later)
• Full Disk Access permission
• Contacts permission (for name resolution)
• Automation permission for Messages.app (send only)

Development

cd swift
swift build           # Debug build
swift build -c release  # Release build
swift test            # Run tests

📄 License

MIT