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
amp mcp add imessage -- npx -y imessage-mcp@latest
Claude Code
claude mcp add --scope user imessage -- npx -y imessage-mcp@latest
Or install the plugin: /plugin marketplace add anipotts/imessage-mcp, then /plugin install imessage-mcp@anipotts.
Claude Desktop
Download imessage-mcp.mcpb and double-click it, or install iMessage History from Settings > Extensions if it is listed there. To update a bundle you installed yourself, download the newest one and double-click it again.
Then turn on Claude in Full Disk Access and quit and reopen Claude.
Cline
Add the standard config to cline_mcp_settings.json (docs).
Codex
codex mcp add imessage -- npx -y imessage-mcp@latest
Or in ~/.codex/config.toml:
[mcp_servers.imessage]
command = "npx"
args = ["-y", "imessage-mcp@latest"]
Copilot CLI
Run /mcp add, or add the standard config to ~/.copilot/mcp-config.json with "type": "local".
Cursor
Or add the standard config to ~/.cursor/mcp.json.
Gemini CLI
Add the standard config to ~/.gemini/settings.json.
Goose
JetBrains (Junie)
Add the standard config to .junie/mcp/mcp.json, or type /mcp in Junie CLI.
Kiro
opencode
In ~/.config/opencode/opencode.json:
{
"$schema": "https://opencode.ai/config.json",
"mcp": {
"imessage": { "type": "local", "command": ["npx", "-y", "imessage-mcp@latest"], "enabled": true }
}
}
VS Code
code --add-mcp '{"name":"imessage","command":"npx","args":["-y","imessage-mcp@latest"]}'
Warp, Windsurf, Zed, and others
Add the standard config in the client's MCP settings. Zed uses context_servers with "source": "custom".
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:
| prompt | what it does |
|---|
catch_up | Who is waiting on a reply from you, and what they need |
draft_reply | A reply in your own texting style. You send it; this server cannot. |
recap | Your week in messages: volume, busiest conversations, anyone still waiting |
Clients that attach resources can use imessage://conversations and imessage://conversations/{chat_id}.
| tool | what it does |
|---|
search_messages | Search by substring, exact text, token, or phrase, in message text, conversation names, or attachment names |
get_conversation | Read a conversation by chat_id or by a contact or group name, with edits, reactions, receipts, replies, and attachments |
list_conversations | Find conversations by contact, service, kind, reply state, or date, each with its latest message, newest first or by who you text most |
get_attachment | Show one attachment: images as a JPEG with metadata removed, text files as text |
sync_messages | Pull every change since a cursor: new, edited, unsent, and deleted messages, reactions, and receipts |
analyze_communication | Message counts by hour and weekday, response times, streaks, and who starts conversations |
resolve_contact | Match a name, phone number, or email to a contact, and report ambiguity rather than guess |
server_status | Version, update availability, access, index state, and schema support |
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"].
| option | description |
|---|
--privacy <mode> | The most any caller can see. full (default), redacted (names and masked handles, calendar days, no message text or filenames), or aggregate (counts only). A call can ask for a stricter mode, never a looser one. env IMESSAGE_PRIVACY |
--contacts <mode> | live (default) names handles from your Contacts; none shows handles only. env IMESSAGE_CONTACTS |
--database <path> | Read a copy of chat.db instead of this Mac's Messages. env IMESSAGE_DB |
--transport http --port <n> | Serve MCP over HTTP on 127.0.0.1 instead of stdio. Requires IMESSAGE_API_TOKEN or IMESSAGE_API_TOKEN_FILE. IMESSAGE_ALLOWED_HOSTS and IMESSAGE_ALLOWED_ORIGINS take comma-separated lists; both default to localhost. |
IMESSAGE_CACHE=0 | Keep the search index in memory only |
IMESSAGE_WARM_SEARCH=0 | Build the search index on the first search instead of at startup |
IMESSAGE_UPDATE_CHECK=0 | Turn off the version check |
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
npm run e2e
npm run perf
Tests use synthetic data only. See CONTRIBUTING.md.
License
MIT