iMessage Max

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

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

Distribution Status

The project now ships a single Swift implementation:

• GitHub releases
• Homebrew
• source builds
• Codex plugin metadata
• Claude Desktop MCPB metadata

The old Python package has been retired and removed from the repository. Everything current lives under swift/.

Features

• 11 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 Contact A and I talk about yesterday?"
→ find_chat(participants=["Contact A"]) + get_messages(since="yesterday")

"Show me the exact details for this thread before I reply"
→ get_chat_details(chat_id="chat123")

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

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

Common Agent Workflows

The tools work best when an agent uses them as short workflows instead of isolated one-off calls.

Agents should treat chat_id values like chat123 as internal handles for tool calls and exact sends. When explaining results to a person, use the returned chat name, group name, or participant-derived label instead of saying "Chat 123."

Find the right conversation, then read it

find_chat(participants=["Contact A"])
get_chat_details(chat_id="chat123")
get_messages(chat_id="chat123", since="yesterday", limit=50)

Use this when the person matters more than the exact thread id.

Search first, then zoom in

search(query="launch timeline", limit=10)
get_context(message_id="msg_456", before=5, after=10)

Use this when you know the topic but not where it was discussed.

Check what needs attention

get_unread()
get_active_conversations(hours=24, min_exchanges=2)

Use this to surface unread threads and active conversations after a broad chat-list sweep.

Work with attachments safely

list_attachments(chat_id="chat123", type="image", since="30d")
get_attachment(attachment_id="att123", variant="vision")

Use list_attachments to discover the message where files were shared first. It still returns exact attachment ids and local-availability state before you fetch a file.

Send with exact targeting when it matters

find_chat(participants=["Contact A", "Contact B"])
send(chat_id="chat456", text="Please use the latest draft")

For sensitive sends, prefer resolving the exact chat first and then using chat_id so the message lands in the intended thread.

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

For local development, advanced setup, and the signed install workflow, see:

• swift/README.md

Client Icon Metadata

iMessage Max ships icons for the main MCP protocol surface and the client packag

... View full README on GitHub