io.github.cyberpapiii/imessage-max

Install

Config snippet generator goes here (5 client tabs)

README

<p align="center">
  <img src="icon.png" alt="iMessage Max" width="128">
</p>

# 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)

```bash
brew tap cyberpapiii/tap
brew install imessage-max
```

### From Source

```bash
git clone https://github.com/cyberpapiii/imessage-max.git
cd imessage-max/swift
swift build -c release

# Binary is at .build/release/imessage-max
```

### Stable Dev Install Workflow

For local development, use the built-in `make` workflow in `swift/` instead of
manually rebuilding and re-granting permissions:

```bash
cd swift
make setup-signing   # one-time: create persistent signing identity
make install         # build, sign, restart launchd service, verify health
```

Why this matters:
- it signs the binary with a persistent local identity so Full Disk Access can persist across rebuilds
- it replaces the release binary in place
- it restarts the launchd-managed `local.imessage-max` service on port `8080`
- it verifies the service is healthy after install

Useful commands:

```bash
cd swift
make status   # show process, signature, version, health
make restart  # restart the launchd service
make logs     # tail the stderr log
make clean    # remove debug artifacts and clear logs
```

## 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:
```bash
# 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:**
```json
{
  "mcpServers": {
    "imessage": {
      "command": "/opt/homebrew/Cellar/imessage-max/VERSION/bin/imessage-max"
    }
  }
}
```

**For source builds:**
```json
{
  "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.

### Launchd Service

If you are running iMessage Max as a background HTTP service, the intended
development path is the launchd-managed binary at:

`~/Library/LaunchAgents/local.imessage-max.plist`

That plist should point at:

`/Users/YOU/.../imessage-max/swift/.build/release/imessage-max --http --port 8080`

The `make install` workflow updates that binary in place and restarts the
service cleanly.

## Tools

### find_chat
Find chats by participants, name, or recent content.

```python
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.

```python
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 spe