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:

Modern clients probe with server/discover and send the required MCP-Protocol-Version, Mcp-Method, and (for tools/call) Mcp-Name headers over HTTP. Legacy clients keep working unchanged. No client migration is required, and legacy support stays as long as real clients depend on it.

The server implements tools only. It has no prompts, resources, completion, subscriptions, tasks, or MRTR flows, on purpose. The official conformance suite runs against both eras with the documented baseline in docs/conformance-baseline.yml.

Client icon metadata

iMessage Max ships icons for the main MCP protocol surface and the client packaging surfaces that use their own metadata:

• MCP 2025-11-25 initialize responses include PNG serverInfo.icons.
• Each tool advertises a compact PNG tool icon.
• Codex plugin metadata lives in .codex-plugin/plugin.json and uses assets/codex/icon.png plus assets/codex/logo.png.
• Claude Desktop / MCPB metadata lives in mcpb/manifest.json and uses PNG assets under mcpb/assets/.

The committed PNG source set is under assets/icons/ at 16x16, 32x32, 64x64, 128x128, 256x256, and 512x512.

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. After changing the grant, relaunch the server; macOS applies Full Disk Access only to processes started after the change.

In the file picker, press ⌘+Shift+G and paste the path to go straight there.

2. Grant Contacts access

Required to resolve phone numbers to names. The server only asks for access when it is started from a terminal; launchd and MCP clients start it headless, and a headless process never prompts. Grant access once with imessage-max --request-contacts-access from a terminal, then restart the service. --contacts-policy request|skip (or IMESSAGE_MAX_CONTACTS_POLICY) overrides the terminal detection.

System Settings → Privacy & Security → Contacts → add imessage-max is the manual alternative.

3. Configure your MCP client

Add imessage-max to your MCP client's server configuration.

Many MCP clients use a JSON structure like this:

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"
    }
  }
}

If your client uses a different config format, point it at the same binary path.

4. Reconnect your MCP client

After saving the config, reconnect or restart your MCP client. The server should appear in the available tools, and you can verify the connection with diagnose.

Tools

find_chat

Find chats by participants, name, or recent content.

By default, chats Messages.app has filtered into Unknown Senders or Junk are hidden. The response carries filtered_hidden, the number of chats the filter removed from this view; pass include_filtered=True to see them.

find_chat(participants=["Contact A"])              # Find a direct chat
find_chat(participants=["Contact A", "Contact B"]) # Find a group with both
find_chat(name="Project Group")                    # Find by chat name
find_chat(contains_recent="latest draft")          # Find by recent content
find_chat(name="Project Group", include_filtered=True)  # Also search junk / unknown-sender chats

get_chat_details

Inspect a known thread without opening the full conversation.

get_chat_details(chat_id="chat123")                          # Participants, handles, state, last message
get_chat_details(chat_id="chat123", include_shared_summary=false) # Skip recent shared summary

get_messages

Retrieve messages with flexible filtering. Returns metadata for media. Explicit chat_id lookups are never filtered.

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="Contact A")  # From specific person
get_messages(chat_id="chat123", has="links")        # Messages that contain a URL

has filters by content type (links, attachments, images). links includes link messages Messages stores as URL preview balloons (the common case on macOS 26).

Group system messages (renames, members added or removed, someone leaving) come back with text: null and an event object: {"type": "rename", "title": "Trip"}, {"type": "participant_added", "participant": "Alice"}, {"type": "participant_removed", ...}, {"type": "left"}, or {"type": "other", "item_type": N} for event kinds the server does not name. Chat previews describe the same events in words ("renamed the group to Trip").