imessage-mcp

imessage-mcp

Search and read your Messages history from Claude, Codex, Cursor, VS Code, and any other MCP client.

Read-only. Runs on your Mac. No accounts, no cloud service, nothing to compile.

• Finds messages by words, exact text, or phrase across iMessage, SMS, MMS, and RCS
• Reads whole conversations with edits, unsent messages, reactions, replies, and read receipts
• Shows photos people sent you, with location data removed
• Keeps up with new messages through a change feed, and answers counts and response-time questions

Install

Requirements: macOS 14 or newer. Node.js 24.16 or newer for npx installs (Claude Desktop brings its own). Use Node 24 LTS for encrypted cache support. Runtimes without SQLite checkpoint APIs, including Node 25, search in memory and rebuild after a restart; doctor reports this.

Standard config, for any client that reads mcpServers JSON:

{
  "mcpServers": {
    "imessage": {
      "command": "npx",
      "args": ["-y", "imessage-mcp@latest"]
    }
  }
}

Then give the app that runs it Full Disk Access: System Settings > Privacy & Security > Full Disk Access, turn on the app (Claude, your terminal, Cursor, VS Code, ...), then quit it fully and reopen it. Not sure which app? Run npx -y imessage-mcp@latest doctor from that app's terminal and it tells you. Until access is granted, every tool answers with these same steps.

amp mcp add imessage -- npx -y imessage-mcp@latest

claude mcp add --scope user imessage -- npx -y imessage-mcp@latest

codex mcp add imessage -- npx -y imessage-mcp@latest

[mcp_servers.imessage]
command = "npx"
args = ["-y", "imessage-mcp@latest"]

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "imessage": { "type": "local", "command": ["npx", "-y", "imessage-mcp@latest"], "enabled": true }
  }
}

code --add-mcp '{"name":"imessage","command":"npx","args":["-y","imessage-mcp@latest"]}'

If a GUI app reports that npx was not found, it cannot see your Node installation: use the full path from which npx as the command.

Use it

Ask in plain words: "catch me up on my texts", "find the message about the dinner reservation", "how fast does Sam usually reply?". Three prompts are also in your client's prompt menu:

Clients that attach resources can use imessage://conversations and imessage://conversations/{chat_id}.

Tools

Every tool is read-only and marked readOnlyHint. Results use plain ids (message_id, chat_id, attachment_id) you can pass between tools.

Apple can record the same message in several conversations. Search returns that message once with all canonical chat_ids and their conversations labels. A single membership also includes chat_id and conversation; for shared results, pass the relevant id from chat_ids to get_conversation. Only Apple's explicit lookup evidence combines chat aliases. Shared messages do not combine unrelated conversations.

Global and contact message counts deduplicate shared records within the requested scope. Conversation timelines and sequence metrics retain each recorded membership, so adding per-conversation counts can exceed the global count. Sync includes chat_ids on changes and emits message_membership_changed with previous_chat_ids; its changed_at is null because Apple does not timestamp these joins. Logged memberships describe the change when observed; available text, sender and receipt fields describe current source state. Upgrading the index format rebuilds its cache once and invalidates older sync cursors; start a new sync when it returns DATABASE_CHANGED.

Contact names expand to the selected person's addresses. An exact phone number or email scopes only that address, even when Contacts has conflicting labels. resolve_contact still reports ambiguous identity; address scoping does not merge people or include their other addresses. For an address-like group title, search with the conversation_names scope and use the selected chat_id.

Every tool's output schema accepts both its success envelope and the structured error envelope, so strict clients can expose the original reason and recovery hints.

Conversation reads are strict by default. When a body or relationship cannot be recovered completely, the error explains the allow_partial: true retry. Partial results retain completeness, warnings and each event's row_status; inspect these before citing evidence. Narrower dates or around_message_id can avoid an unrelated damaged event. Structural failures still fail closed.

Configuration

Add options to args, for example ["-y", "imessage-mcp@latest", "--privacy", "redacted"].

Privacy and security

• Read-only. The server opens the Messages database read-only and has no tool that sends, edits, reacts, or marks anything read.
• Local. No accounts, telemetry, or analytics. The only network request is an optional version check to the npm registry.
• Your client sees what you ask for. Results go to the MCP client you use and its model provider, under their policies. --privacy redacted or aggregate limits what leaves the server.
• Search index. Built on your Mac and, when SQLite checkpoint APIs are available, cached encrypted in ~/Library/Caches/imessage-mcp, with a key derived from your Messages database, so it opens only for an app that can already read your messages. Deleting it is always safe. server_status reports an unavailable or failed cache while searches continue from memory.
• Untrusted content. Messages can contain text written to manipulate an AI. The server tells clients to treat all message content as data, never as instructions.

Details: SECURITY.md and PRIVACY.md.

Development

npm ci
npm test      # unit tests on synthetic Messages databases
npm run e2e   # launches the built server over stdio and HTTP
npm run perf  # one-million-message performance gates

Tests use synthetic data only. See CONTRIBUTING.md.

Dependency PRs use protected auto-merge through a repository-scoped GitHub App, without personal-token renewal. A daily health check detects authentication failures and stalled updates; see maintenance and recovery.

• Retire the unused owner-token copies after the App migration is verified and rollback is no longer needed.
• After extended inactivity, verify that GitHub has not disabled scheduled workflows. Dependency merges do not publish a release.

License

MIT