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

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.

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 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.
• 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.

License

MIT