imessage-mcp

# imessage-mcp

Private, read-only MCP for Apple Messages on Mac.<br>
Search and analyze iMessage, SMS, MMS, and RCS history.

The server runs locally, collects no telemetry, and keeps its search index in memory. Your MCP client controls where tool results are processed.

Every 2.x tool reads data only. Sending and modifying messages are outside the 2.x API.

> [!IMPORTANT]
> SMS, MMS, and RCS with Android users work only when those conversations already appear in Messages on this Mac. Message forwarding or sync must be configured between the iPhone and Mac, subject to Apple, carrier, and regional availability. See [Apple's Messages setup guide](https://support.apple.com/en-euro/guide/messages/ichte16154fb/mac).

![synthetic imessage-mcp output](assets/demo-light.png)

## service coverage

| history visible in Messages | support | notes |
| --- | --- | --- |
| iMessage | supported | blue-bubble history already synced to this Mac |
| SMS | supported | green-bubble history already forwarded or synced to this Mac |
| MMS | supported | Apple may store MMS under the SMS service family |
| RCS | supported when present | Android-originated RCS must already appear in Messages on this Mac |
| unknown Apple service values | detected | returned as `unknown`, never silently relabeled |

Every message and timeline event includes `service_family`. Capability states are authoritative. A missing protocol feature is `unavailable`; schema behavior that has not been certified is `unknown`.

## requirements

- macOS 14 or newer on Apple silicon or Intel
- an active Node.js 22, 24, or 26 release
- Apple Messages history in the Mac `chat.db` schema
- Full Disk Access for the MCP client that launches the server

The supported inputs are a live Mac `chat.db` and a faithful copy of that same Mac schema. iPhone backup manifests, Linux, containers, Docker, and portable contact bundles are outside the 2.x support boundary.

## install

```sh
npm install -g imessage-mcp@2.0.0-beta.2
umask 077
openssl rand -base64 32 > "$HOME/.imessage-mcp-reference-key"
openssl rand -base64 32 > "$HOME/.imessage-mcp-database-id"
export IMESSAGE_REFERENCE_KEY_FILE="$HOME/.imessage-mcp-reference-key"
export IMESSAGE_DATABASE_ID_FILE="$HOME/.imessage-mcp-database-id"
imessage-mcp doctor
```

This exact version installs the 2.0 prerelease. Upgrade only by explicitly selecting a newer exact version. The stable setup will remain version-pinned so an existing Full Disk Access client never begins executing a different package only because an npm dist-tag moved.

The default transport is stdio. It reads `~/Library/Messages/chat.db` and uses unified Contacts when the live Contacts permission is already available. A reference key and a separate database identity are mandatory. Operator-owned `0600` files are preferred; protected process environments may supply the values directly. The server never writes either value.

The server never opens System Settings, requests a permission through UI automation, changes Messages settings, or persists a database change. It sets connection-local `query_only` and timeout pragmas after opening SQLite read-only. `doctor` reports remediation only.

## privacy modes

The startup mode is a disclosure ceiling. A request can choose the same mode or a stricter mode, never a more revealing one.

| mode | returned data |
| --- | --- |
| `full` | current visible bodies, names, exact handles, exact timestamps, and attachment metadata |
| `redacted` | names, masked handles, calendar days, and opaque references; no bodies, snippets, filenames, or paths |
| `aggregate` | exact identity-free counts and metrics; no names, handles, snippets, paths, or record references |

Stdio defaults to `full`. HTTP defaults to `redacted`.

Aggregate mode is deterministic redaction. It is not differential privacy, k-anonymity, or a formal anonymity guarantee. Body search is allowed in every mode, but outputs follow the selected privacy boundary: full returns snippets, redacted returns name and day metadata, and aggregate returns counts only.

Set a stricter ceiling at startup:

```json
{
  "mcpServers": {
    "imessage": {
      "command": "npx",
      "args": ["-y", "imessage-mcp@2.0.0-beta.2"],
      "env": {
        "IMESSAGE_PRIVACY": "redacted",
        "IMESSAGE_REFERENCE_KEY_FILE": "/Users/you/.imessage-mcp-reference-key",
        "IMESSAGE_DATABASE_ID_FILE": "/Users/you/.imessage-mcp-database-id"
      }
    }
  }
}
```

Valid values are `full`, `redacted`, and `aggregate`.

## seven tools

| tool | purpose |
| --- | --- |
| `server_status` | API and package versions, privacy ceiling, detected services, schema capabilities, source mode, decoder health, and search-index state |
| `resolve_contact` | resolve a nonempty name or handle to one unique contact or structured candidates without guessing |
| `list_conversations` | list direct and group chats with contact, service, reply, local-date, and timezone filters |
| `get_conversation` | read the latest visible timeline with keyset pagination, around-message context, reactions, receipts, replies, attachments, and group events |
| `search_messages` | global literal substring, exact, token, or phrase search with explicit metadata scopes |
| `analyze_communication` | one typed metric over global, contact, or conversation scope with formulas and service partitions |
| `sync_messages` | stateless pulls for messages, edits, retractions, reaction changes, receipt changes, and group events |

There are no 1.x aliases, dump/export tool, watcher, push subscription, prompt, or MCP resource in 2.x.

## client setup

### codex

Add the server through Codex MCP settings or the CLI:

```sh
codex mcp add --env IMESSAGE_REFERENCE_KEY_FILE="$HOME/.imessage-mcp-reference-key" \
  --env IMESSAGE_DATABASE_ID_FILE="$HOME/.imessage-mcp-database-id" \
  imessage -- npx -y imessage-mcp@2.0.0-beta.2
```

Grant Full Disk Access to the Codex application that launches the process, then restart that application.

### claude desktop

Add this entry to Claude Desktop's MCP configuration:

```json
{
  "mcpServers": {
    "imessage": {
      "command": "npx",
      "args": ["-y", "imessage-mcp@2.0.0-beta.2"],
      "env": {
        "IMESSAGE_REFERENCE_KEY_FILE": "/Users/you/.imessage-mcp-reference-key",
        "IMESSAGE_DATABASE_ID_FILE": "/Users/you/.imessage-mcp-database-id"
      }
    }
  }
}
```

Grant Full Disk Access to Claude Desktop, restart it, and run `server_status`.

### claude code

```sh
claude mcp add imessage -e IMESSAGE_REFERENCE_KEY_FILE="$HOME/.imessage-mcp-reference-key" \
  -e IMESSAGE_DATABASE_ID_FILE="$HOME/.imessage-mcp-database-id" \
  -- npx -y imessage-mcp@2.0.0-beta.2
```

### cursor

Use the same `mcpServers.imessage` JSON entry in Cursor's MCP settings. Grant Full Disk Access to Cursor and restart it before testing.

Client configuration tests use isolated temporary settings. Release verification never changes an active user configuration.

## live and copied databases

The default database is the live Mac source:

```text
~/Library/Messages/chat.db
```

Use a faithful copy for testing or archival reads:

```sh
imessage-mcp --database /absolute/path/to/copied-chat.db
```

Copied databases use handles and reject pairing with this Mac's live Contacts, which may belong to a different archive owner. A matching copied AddressBook source is not accepted by the 2.0 CLI. A live source continues without Contacts when permission is unavailable, returning exact or masked handles according to the privacy mode.

The canonical default path is certified as `live` whether it is selected implicitly or supplied explicitly with `--database`. Any other path is treated as a `copy`. A copied source is an immutable snapshot for `sync_messages`: the first call returns its latest cursor, unchanged follow-up calls stay empty, and any byte or database-watermark change returns `DATABASE_CHANGED`. Replace or update a copy only between server runs, then start with a fresh cursor.

Keep copied database files and their parent directory under the operator's control and unchanged for the server process's lifetime.

Database-scoped references survive server restarts and faithful copies only when they use both the same reference key and the same operator-assigned database identity. Generate a unique database identity for each live database or unrelated archive. Copy that identity only with certified faithful copies. If a reference key is accidentally reused with a different database identity, the resulting lineages and opaque references still differ. Losing or rotating either value invalidates existing references and cursors without changing Messages data.

`IMESSAGE_REFERENCE_KEY_FILE` and `IMESSAGE_DATABASE_ID_FILE` are preferred. Direct inputs through `IMESSAGE_REFERENCE_KEY` and `IMESSAGE_DATABASE_ID` are available for process supervisors that already protect environment values. Set exactly one source for each value. The server never exposes the database identity. Each paginated traversal is frozen at its first database watermark, so new activity requires a fresh query or `sync_messages`.

Live sync is supported only while Messages is the sole writer of the live Apple database. Cursors authenticate structural relationships separately from exact body/lifecycle and receipt state, so one change class cannot authorize another. They keep compact exact content state for a one-hour safety window around recent messages, exceeding Apple's documented 15-minute edit and two-minute unsend windows, and fully hash older content. Receipt state is normalized to each cursor's exact checkpoint before comparison. If an older row changes without its matching monotonic edit, retraction, or receipt evidence, `sync_messages` returns `DATABASE_CHANGED` and requires a fresh cursor. Direct writes by SQLite tools, migration utilities, or third-party software are outside the live-sync boundary and require a server restart plus a fresh cursor. See [Apple's edit and