io.github.cyberpapiii/imessage-max
AI-optimized MCP server for iMessage on macOS. Read, search, and send messages.
Ask AI about io.github.cyberpapiii/imessage-max
Powered by Claude Β· Grounded in docs
I know everything about io.github.cyberpapiii/imessage-max. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Reviews
Documentation
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
Setup
1. Grant Full Disk Access
Required to read ~/Library/Messages/chat.db:
- Open System Settings β Privacy & Security β Full Disk Access
- 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/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.
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 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
| Variant | Resolution | Use Case | Token Cost |
|---|---|---|---|
vision (default) | 1568px | AI analysis, OCR | ~1,600 tokens |
thumb | 400px | Quick preview | ~200 tokens |
full | Original | Maximum detail | Varies |
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
Troubleshooting
Contacts showing as phone numbers
Run diagnose to check status. If contacts_authorized is false:
- Add the
imessage-maxbinary 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
- Check config file syntax is valid JSON
- Verify the binary path is correct
- 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
