imessage-mcp
Search, read, and analyze your local Mac Messages history through MCP, read-only and on-device.
Search messages by text, contact, date range, direction, group chat, or attachment presence, with pagination.
Read full conversations and reply threads, including edits, unsent messages, reactions, read receipts, effects, and attachment metadata.
Explore contacts and group chats: resolve/list contacts, get per-contact or per-group stats, members, activity timelines, and yearly breakdowns.
Run communication analytics: message counts, temporal heatmaps, response/read timing, who initiates conversations, streaks, double-texting, conversation gaps, forgotten contacts, first/last messages, “on this day,” and yearly wrapped summaries.
Check for new messages since a baseline and reset that baseline.
Get built-in help describing available tools and usage examples.
The server is read-only: it cannot send, edit, react to, or mark messages as read.
Allows for the exploration of local Apple messaging data, including iMessage history, contact information from the AddressBook, and metadata like message effects and tapback reactions.
Provides read-only access to iMessage history for full-text search, conversation analysis, reaction tracking, and detailed messaging statistics such as streaks and response patterns.
Integrates with the local macOS environment to access the iMessage database (chat.db) and AddressBook contacts to provide insights into messaging history and trends.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@imessage-mcp Search my messages with Sarah for the address she sent last week"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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@latestclaude mcp add --scope user imessage -- npx -y imessage-mcp@latestOr install the plugin: /plugin marketplace add anipottsbuilds/imessage-mcp, then /plugin install imessage-mcp@anipotts.
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.
Add the standard config to cline_mcp_settings.json (docs).
codex mcp add imessage -- npx -y imessage-mcp@latestOr in ~/.codex/config.toml:
[mcp_servers.imessage]
command = "npx"
args = ["-y", "imessage-mcp@latest"]Run /mcp add, or add the standard config to ~/.copilot/mcp-config.json with "type": "local".
Or add the standard config to ~/.cursor/mcp.json.
Add the standard config to ~/.gemini/settings.json.
Add the standard config to .junie/mcp/mcp.json, or type /mcp in Junie CLI.
In ~/.config/opencode/opencode.json:
{
"$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"]}'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.
Related MCP server: jons-mcp-imessage
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 |
| Who is waiting on a reply from you, and what they need |
| A reply in your own texting style. You send it; this server cannot. |
| 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 by substring, exact text, token, or phrase. Message text by default; conversation names and attachment filenames are opt-in. Filter by service, sent or received, and date |
| Read a conversation by |
| Find conversations by contact, service, kind, reply state, or date, each with its latest message, newest first or by who you text most |
| Show one attachment from |
| Pull every change since a cursor: new, edited, unsent, and deleted messages, conversation memberships, reactions, and receipts |
| Message counts by hour and weekday, response times, streaks, and who starts conversations |
| Match a name, phone number, or email to a contact in your Mac's Address Book, and report ambiguity rather than guess |
| Version, update availability, privacy mode, index and cache state, schema support, conversation membership counts, and Contacts access |
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.
Pagination cursors are opaque and scoped to the running server. Pass them back unchanged; after a server restart or DATABASE_CHANGED, begin that traversal again. Sync cursors retain their separate checkpoint-backed behavior.
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"].
option | description |
| The most any caller can see. |
|
|
| Read a copy of |
| Serve MCP over HTTP on 127.0.0.1 instead of stdio. Requires |
| Keep the search index in memory only |
| Build the search index on the first search instead of at startup |
| 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, 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_statusreports 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 gatesTests 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
Available Tools
26 toolscheck_new_messagesARead-only
Check for new messages since your last check. First call sets a baseline. Subsequent calls report what arrived since.
Inputs: reset, include_text, limit, contact.
contact_statsBRead-only
Deep per-contact analytics: message volumes, response time estimates, conversation patterns, and yearly trends.
Inputs: contact (required), date_from, date_to.
conversation_gapsARead-only
Find the longest silences in a conversation. Detects periods where you and a contact stopped talking — falling-outs, busy periods, or drifting apart. Shows gap duration and when it happened.
Inputs: contact (required), min_gap_days, limit.
double_textsARead-only
Detect double-texting and unanswered message patterns. Finds when you (or a contact) sent multiple consecutive messages without a reply. Shows frequency, longest bursts, and who does it more. Omit contact for a global ranking of who you double-text the most.
Inputs: contact, min_consecutive, date_from, date_to, +1 more.
first_last_messageARead-only
The very first and very last message ever exchanged with a contact. People use this for sentimental lookups like 'what was the first text I sent my partner?' or 'what was the last thing my grandparent texted me?'
Inputs: contact (required).
forgotten_contactsARead-only
Find dormant relationships — contacts you used to message but haven't talked to in a long time. Great for reconnecting with people you've lost touch with. By default excludes contacts you've never replied to.
Inputs: min_messages, inactive_days, include_all, limit.
get_contactBRead-only
Deep info on a specific contact: tier, message stats, yearly breakdown, and recent messages.
Inputs: contact (required).
get_conversationARead-only
Get a full conversation thread with a specific contact or chat. Supports cursor-based pagination via before_rowid (backward) or after_rowid (forward) for scrolling through history.
Inputs: contact, chat_id, limit, before_rowid, +3 more.
get_edited_messagesARead-only
Find edited and unsent (retracted) messages. Queries date_retracted and date_edited columns. Returns message list with timestamps and per-contact stats.
Inputs: contact, type, date_from, date_to, +1 more.
get_group_chatARead-only
Detailed info on a specific group chat: all members with per-member message counts, activity timeline, and recent messages.
Inputs: chat_id, name.
get_message_effectsBRead-only
iMessage expressive send effects and screen effects analytics: slam, loud, gentle, invisible ink, confetti, fireworks, balloons, lasers, etc. Queries expressive_send_style_id.
Inputs: contact, date_from, date_to, limit.
get_reactionsARead-only
Tapback/reaction analytics: distribution by type, top reactors, most-reacted messages, emoji breakdown. Queries associated_message_type 2000-2005 for love/like/dislike/laugh/emphasize/question reactions.
Inputs: contact, reaction_type, date_from, date_to, +2 more.
get_read_receiptsBRead-only
Read receipt and delivery timing analytics: per-contact read latency stats, unread patterns, fastest/slowest readers. Queries date_read and date_delivered columns.
Inputs: contact, date_from, date_to, limit.
get_threadARead-only
Reconstruct iMessage reply threads using thread_originator_guid. Returns nested thread trees with parent message and all replies in order.
Inputs: message_guid, contact, limit.
helpARead-only
Show the imessage-mcp guide: all 26 tools and usage examples. Call this when you're unsure what's available.
Inputs: no named parameters.
list_attachmentsARead-only
Query message attachments (images, videos, audio, documents) with filtering by contact, MIME type, and date range. Returns file metadata, not file contents.
Inputs: contact, mime_type, date_from, date_to, +2 more.
list_contactsARead-only
List all contacts with message counts and tier assignments. Supports filtering by tier and minimum message threshold. By default, only shows contacts you've actually messaged (replied to). Use include_all to see all.
Inputs: tier, min_messages, sort_by, include_all, +1 more.
list_group_chatsBRead-only
List all group chats with member counts, message volumes, and activity dates. Group chats have multiple participants.
Inputs: min_messages, sort_by, limit.
message_statsARead-only
Aggregate message statistics with flexible time-series grouping. Returns counts, sent/received splits, and averages grouped by day, week, month, year, hour, or day-of-week. By default excludes contacts you've never replied to.
Inputs: contact, date_from, date_to, group_by, +1 more.
on_this_dayARead-only
Messages from this date in previous years — like 'Memories' for iMessage. Shows what you and your contacts were talking about exactly 1, 2, 3+ years ago today. By default excludes contacts you've never replied to.
Inputs: date, month_day, contact, include_all, +1 more.
resolve_contactARead-only
Fuzzy-match a name, phone number, or email to a contact record. Uses multi-level resolution: exact match, digits, fuzzy, and macOS AddressBook.
Inputs: query (required).
search_messagesARead-only
Full-text search across all iMessages with rich filtering. Supports query text, contact, date range, direction, group chat, and attachment filters. By default, only searches contacts you've messaged. Use include_all to search everything.
Inputs: query, contact, date_from, date_to, +7 more.
streaksARead-only
Consecutive-day messaging streaks with contacts. Like Snapchat streaks but for iMessage. Shows longest streak, when it happened, and current streak status. By default excludes contacts you've never replied to.
Inputs: contact, min_streak, include_all, limit.
temporal_heatmapARead-only
Generate a 7x24 activity heatmap (day-of-week x hour-of-day). Returns message counts for each of the 168 weekly time slots. By default excludes contacts you've never replied to.
Inputs: contact, date_from, date_to, sent_only, +1 more.
who_initiatesARead-only
Who starts conversations? After a gap of N hours, the next message is a 'conversation initiation.' Shows per-contact who reaches out first and how often. Answers 'do I always text first?' By default excludes contacts you've never replied to.
Inputs: contact, gap_hours, min_conversations, date_from, +3 more.
yearly_wrappedARead-only
Your iMessage Year in Review — like Spotify Wrapped but for texting. Returns a complete summary of a year: total messages, top contacts, busiest day, monthly trends, reactions, group chats, media shared, late-night texting, new contacts, and effects used. By default excludes contacts you've never replied to. Defaults to last year.
Inputs: year, include_all.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 26 tools
Each tool has a clearly distinct purpose with no significant overlap; for example, 'get_contact' retrieves detailed contact info, while 'contact_stats' provides analytics, and 'list_contacts' lists contacts with counts. The descriptions are specific enough to prevent misselection, covering unique aspects like message effects, reactions, streaks, or temporal analysis.
Tool names follow a consistent verb_noun pattern throughout, such as 'check_new_messages', 'get_contact', 'list_attachments', and 'search_messages'. There are no deviations in style (e.g., all use snake_case) or verb usage, making the set predictable and easy to navigate.
With 26 tools, the count feels heavy for an iMessage analytics server, potentially overwhelming for agents. While the tools cover a wide range of features (e.g., stats, searches, temporal analysis), it borders on excessive, as some functionalities could be consolidated (e.g., multiple analytics tools like 'contact_stats', 'message_stats', 'yearly_wrapped').
The tool surface is comprehensive for iMessage analytics, covering CRUD-like operations (e.g., 'get_conversation', 'search_messages'), lifecycle coverage (e.g., 'first_last_message', 'on_this_day'), and extensive analytics (e.g., 'streaks', 'who_initiates', 'yearly_wrapped'). There are no obvious gaps; agents can perform detailed queries, statistical analysis, and historical lookups without dead ends.
Maintenance
Related MCP Connectors
Explore your Messages SQLite database to browse tables and inspect schemas with ease. Run flexible…
Read your Chert FaceTime and iMessage lines, calls, transcripts and messages.
Read, search and answer your messages on WhatsApp, iMessage, Slack, Telegram and 17 more networks.
iMessage for AI agents, from your iPhone. No Mac needed, and you choose which chats they read.
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceProvides read-only access to local Beeper message history on macOS, enabling users to search conversations, read messages, and list recent chats through natural language queries. Supports both SQLite and IndexedDB storage formats with privacy-focused local-only operation.1-
- AlicenseAqualityDmaintenanceEnables AI assistants to read iMessage history and send messages on macOS. Supports conversation listing, message search with keyword and semantic modes, contact lookup, and sending messages to existing conversations.1311MIT
- AlicenseNot gradedqualityBmaintenanceEnables AI assistants to read, search, and send iMessages with features like contact name resolution, session grouping, and attachment listing. It provides intent-aligned tools to efficiently navigate conversation history and manage messages through natural language queries.7MIT
- AlicenseNot gradedqualityCmaintenanceA read-only MCP server for macOS that enables users to search through iMessage history and analyze conversation patterns using AI-powered tools. It provides detailed statistics on messaging habits, streaks, and contact analytics while keeping all data private and local.848 npm1-