# imessage-max

A Swift MCP server that lets an agent read, search and send iMessage on macOS, turning phone numbers into contact names.

- MCP server · `type=mcp` · Claude Code, Codex, Cursor, GitHub Copilot, Windsurf (Devin Desktop), Cline, Zed, Gemini CLI · ★ 6
- Author: cyberpapiii
- License: MIT · policy=link-only · description only; the file stays with the author
- Source: https://github.com/cyberpapiii/imessage-max
- Updated: 2026-10-12
- HTML: https://affpapa.org/en/nevibecode/mcp/imessage-max

## What it does

imessage-max ships as a single Swift binary with nothing to install at runtime. It reads `chat.db` read-only; sending requires Automation permission for Messages.app. The thirteen tools follow questions people actually ask rather than database tables: `find_chat`, `get_messages`, `search`, `list_attachments`, `send` and others.

Messages are grouped into sessions, split wherever the gap reaches 4 hours or more. Images come in three variants — vision at 1568px, thumb at 400px, and the original — so a photo need not arrive at full size. Attachment listings state whether a file sits on disk or has been offloaded to iCloud. Phone numbers map to names through macOS Contacts.

Full Disk Access has to be granted before the first run, otherwise `~/Library/Messages/chat.db` stays unreadable. macOS applies that grant only to processes started afterwards, so relaunch the server once you change it. Contacts access is requested when the server starts from a terminal; a process launched headless by an MCP client never prompts, so run `imessage-max --request-contacts-access` from a terminal first and restart the service.

## Requirements
- Needs: Python and uv (commands run via uvx)

## Install

### Claude Code (native platform)

**Platform CLI**
```bash
claude mcp add imessage-max -- uvx imessage-max
```
uvx runs the command named after the package; if the README names another one, use uvx --from imessage-max <command>

### Codex

**Platform CLI**
```bash
codex mcp add imessage-max -- uvx imessage-max
```
uvx runs the command named after the package; if the README names another one, use uvx --from imessage-max <command>

### Cursor

**Config file**
File `.cursor/mcp.json`:
```json
{
    "mcpServers": {
        "imessage-max": {
            "command": "uvx",
            "args": [
                "imessage-max"
            ]
        }
    }
}
```
uvx runs the command named after the package; if the README names another one, use uvx --from imessage-max <command>

### GitHub Copilot

**Config file**
File `.vscode/mcp.json`:
```json
{
    "servers": {
        "imessage-max": {
            "type": "stdio",
            "command": "uvx",
            "args": [
                "imessage-max"
            ]
        }
    }
}
```
uvx runs the command named after the package; if the README names another one, use uvx --from imessage-max <command>

### Gemini CLI

**Platform CLI**
```bash
gemini mcp add imessage-max uvx imessage-max
```
uvx runs the command named after the package; if the README names another one, use uvx --from imessage-max <command>

## When to use it
- find a conversation by person instead of by number
- pull the context around a message about a launch timeline
- see unread threads and active conversations from the last day
- fetch group chat photos at a smaller size
- send a message into the exact thread via `chat_id`

## Example prompts
- Find my chat with Alex and show what we discussed yesterday
- Search my messages for the launch timeline and show the surrounding context
- Send “use the latest draft” to `chat456`

## Similar
- [REA](https://affpapa.org/en/nevibecode/mcp/rea.md) — MCP server · ★ 386989
- [GitHub](https://affpapa.org/en/nevibecode/mcp/github.md) — MCP server · ★ 33918
- [Netdata](https://affpapa.org/en/nevibecode/mcp/netdata.md) — MCP server · ★ 81115
- [browser-use](https://affpapa.org/en/nevibecode/mcp/browser-use.md) — MCP server · ★ 119160
- [Codebase Memory](https://affpapa.org/en/nevibecode/mcp/codebase-memory.md) — MCP server · ★ 47392
- [mcp-server](https://affpapa.org/en/nevibecode/mcp/mcp-server.md) — MCP server · ★ 43872

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md