Imessage Max MCP server

iMessage Max

An MCP (Model Context Protocol) server for iMessage. It lets AI agents read, search, and send your messages, resolving phone numbers to contact names along the way.

Written in Swift. One 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

• 13 tools shaped around questions people actually ask, not around database tables
• Phone numbers resolve to names through macOS Contacts
• Three image variants: vision (1568px), thumb (400px), full (original), so a photo does not have to arrive at full size
• Messages group into sessions, split on gaps of 4 hours or more
• Attachment listings say whether each file is on disk or offloaded to iCloud
• Raw SQLite3 and Core Image GPU acceleration
• Reads chat.db only. Sending needs Automation permission for Messages.app

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 find the message where files were shared. It returns exact attachment ids and says whether each file is on disk, so you know before you fetch.

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

Protocol support

iMessage Max is a dual-era MCP server. Both transports (stdio and HTTP) serve both eras concurrently, selected per request:

Shortened. The full README is on GitHub.