25 tools for searching, analyzing, and exploring your iMessage history on macOS.
Quick Install
Automated & IDE SetupCopy the AI prompt to install this server into Claude Code, Cursor, or another agent — or use 1-click editor setup below.
Not yet automatically verified
We haven't yet run this listing's install command through our automated sandbox check. This isn't a red flag — we're steadily working through the catalog.
Manual Client & Custom JSON ConfigExpand JSON ▾
Client Config & Setup
Choose your client or environment
Target File:
💡 Paste the JSON block into your client's configuration file under mcpServers, then restart the application.
Capabilities & Tool Schemas (8)
Inspect callable tools, capabilities, and parameters exposed to AI agents by IMessage MCP.
search_messagesSearch by substring, exact text, token, or phrase, in message text, conversation names, or attachment names
get_conversationRead a conversation by `chat_id` or by a contact or group name, with edits, reactions, receipts, replies, and attachments
list_conversationsFind conversations by contact, service, kind, reply state, or date
get_attachmentShow one attachment: images as a JPEG with metadata removed, text files as text
sync_messagesPull every change since a cursor: new, edited, unsent, and deleted messages, reactions, and receipts
analyze_communicationMessage counts, activity, response times, and who starts conversations
Documentation Overview
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:
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
Claude Code
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
Or in ~/.codex/config.toml:
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:
VS Code
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}.
Tools
| 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 redactedoraggregatelimits 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
Related MCP Servers
Adoption & maintenance
Factual signals from GitHub, npm, and our automated checks — not a rating.
GitHub stars
25
Stargazers on the source repository.
Last commit
3d ago
Most recent push to the default branch.
Tools exposed
8
Callable tools this server registers over MCP.
Directory activity
1 views
Config copies, upvotes, and views on AllMCPs.
Reviews
No reviews yet — be the first to share how this listing worked for you.
Frequently Asked Questions about IMessage MCP
AllMCPs Directory Badge
Showcase your server listing on GitHub or your project documentation. Embed this dynamic SVG badge to highlight official listing status and live engagement.
Badge Style:
Live Dynamic SVG Preview
Markdown (GitHub README)
[](https://allmcps.com/mcp/imessage-mcp)HTML Embed
<a href="https://allmcps.com/mcp/imessage-mcp"><img src="https://allmcps.com/api/badge/imessage-mcp?style=directory" alt="IMessage MCP on AllMCPs" /></a>