iMessage Max

You run an MCP (Model Context Protocol) server for iMessage that lets AI assistants read and search your messages with contact resolution, while staying read-only. It enriches media, resolves names from macOS Contacts, groups messages into conversations, and is designed for efficient AI consumption with safe read-only access.

How to use

Use an MCP client to query chats and messages through clearly named actions. You can search chats by participants, read recent messages, and fetch media metadata or attachments when needed. Aim for natural questions such as finding a DM with Nick, listing recent group chats, or locating the point where you discussed a topic. The server handles contact resolution and media enrichment to keep responses compact and useful for AI assistants.

How to install

Prerequisites you’ll need before installing the MCP server: UV for Python environments and a macOS setup with appropriate permissions.

# Install UV if you don’t have it
curl -LsSf https://astral.sh/uv/install.sh | sh

Steps to set up permissions and client integration

1) Grant Full Disk Access to the tools that read iMessage data:
- Open System Settings → Privacy & Security → Full Disk Access
- Add your terminal or Python runner (e.g., Terminal.app or uvx path)
- If using UV, also add the Python runtime used by UV (path shown by your system)

2. Grant Contacts access for name resolution:

• Go to Privacy & Security → Contacts
• Add the same tools/processes as above (including UV if used)

Configure Claude Desktop

{
  "mcpServers": {
    "imessage": {
      "command": "uvx",
      "args": ["imessage-max"]
    }
  }
}

Install via pip or UV (quick paths)

From PyPI install for quick setup (requires UV if you want the UV path):

pip install imessage-max

Using UV to run the MCP server

If you’re using UV, install the MCP package via UV and run it through UV as shown in the steps above.

# Install imessage-max with UV
uv pip install imessage-max

From source

If you prefer running from source, install with Python’s package manager directly from the repository.

pip install git+https://github.com/cyberpapiii/imessage-max.git

Available tools

find_chat

Find chats by participants, name, or recent content.

get_messages

Retrieve messages with flexible filtering and media/link enrichment; returns message metadata and attachments.

get_attachment

Retrieve full image content by attachment ID with options for thumbnail or full resolution.

list_chats

Browse recent chats with previews and optional filters for groups or time ranges.

search

Full-text search across all messages with optional filters for participants, groups, or time bounds.

get_context

Get messages surrounding a specific message or query, with before/after context.

get_active_conversations

Find chats with recent back-and-forth activity, with optional group filtering.

list_attachments

List attachments with metadata, filtered by chat or person.

get_unread

Fetch unread messages or a summary, with optional time constraints.

send

Send a message to a contact or group chat (requires Automation permission).

diagnose

Check setup, permissions, and readiness status for the MCP server.