contact_stats
Deep per-contact analytics: message volumes, response time estimates, conversation patterns, and yearly trends.
LABSCO SUMMARY
It reads years of messages and nothing leaves the Mac to make that possible.
Every tool is annotated read-only against two local files, which is what makes auto-approving the calls reasonable. What sets it apart is how far past search it reaches — streaks, who texts first, the longest silence with someone, a whole year summarised — so it answers questions about relationships rather than just locating a message. Set IMESSAGE_SAFE_MODE=1 when you want the analytics without the message bodies.
What it is
A read-only server over the local iMessage database. It touches two files on disk, chat.db and the macOS AddressBook, makes no network requests, and writes nothing back.
What you get
- Full-text search across every message, with filters for contact, date range, direction, group chats and attachments, and cursor-paginated conversation threads for scrolling back through history
- Contacts with message counts and tiers, deep per-contact analytics, and fuzzy resolution of a name, number or email through the AddressBook
- Group chats listed with member counts and volumes, and one chat broken down member by member
- Statistics grouped by day, week, month, year, hour or day-of-week, plus an activity heatmap of weekday against hour of day
- The parts of iMessage most tools skip: tapbacks by type and top reactor, read-receipt and delivery latency per contact, reply threads reconstructed from their originators, edited and unsent messages, and expressive send effects
- Relationship questions asked directly: who starts conversations after a gap, consecutive-day streaks, double-texting patterns, the longest silences with a contact, dormant contacts worth reconnecting with, and the first and last message ever exchanged with someone
- on_this_day for what you were talking about a year ago, and yearly_wrapped for an entire year summarised — top contacts, busiest day, monthly trends, media, late-night texting
- Attachment metadata by contact, MIME type and date — file information, not file contents
- A help tool that prints the guide to every tool with usage examples
Requirements
macOS and Node.js 18+, plus Full Disk Access granted to whatever runs the server — your terminal, Claude Desktop or Cursor — because macOS protects chat.db behind that permission. IMESSAGE_DB points at a database somewhere other than ~/Library/Messages/chat.db, IMESSAGE_SAFE_MODE=1 redacts every message body and returns metadata only, and IMESSAGE_SYNC picks up new messages through FSEvents (watch) or polling. stdio is the default; --transport http --port 3000 serves Streamable HTTP, and IMESSAGE_API_TOKEN then requires a bearer token on those requests. Run it with npx -y imessage-mcp.
Setup effort
One command — npm install -g imessage-mcp
USE CASES
01
Finding a message you can only half describe
Search with a contact and date range, then open the conversation around the hit.
02
Reconnecting with people you have lost touch with
Surface contacts gone quiet for a long time, then see how long the silence has actually run.
03
Settling the question of who texts first
Rank conversation initiations after a gap, and see who does the double-texting.
04
Looking back at a year of messages
Get the full year summarised, and see what you were saying on this date in previous years.
05
Understanding one relationship in detail
Read the contact's stats and yearly trends, then the very first and very last message exchanged.
06
Seeing when you actually message people
Read the counts grouped by hour or weekday, and the 7x24 activity heatmap.
25 tools
Counted once with only startup setup. Other versions, modes or optional credentials may expose a different list.
conversation_gaps
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.
double_texts
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.
first_last_message
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?'
forgotten_contacts
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.
get_contact
Deep info on a specific contact: tier, message stats, yearly breakdown, and recent messages.
get_conversation
Get a full conversation thread with a specific contact or chat. Supports cursor-based pagination via before_rowid for scrolling through history.
get_edited_messages
Find edited and unsent (retracted) messages. Queries date_retracted and date_edited columns. Returns message list with timestamps and per-contact stats.
get_group_chat
Detailed info on a specific group chat: all members with per-member message counts, activity timeline, and recent messages.
get_message_effects
iMessage expressive send effects and screen effects analytics: slam, loud, gentle, invisible ink, confetti, fireworks, balloons, lasers, etc. Queries expressive_send_style_id.
get_reactions
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.
get_read_receipts
Read receipt and delivery timing analytics: per-contact read latency stats, unread patterns, fastest/slowest readers. Queries date_read and date_delivered columns.
get_thread
Reconstruct iMessage reply threads using thread_originator_guid. Returns nested thread trees with parent message and all replies in order.
help
Show the imessage-mcp guide: all 25 tools and usage examples. Call this when you're unsure what's available.
list_attachments
Query message attachments (images, videos, audio, documents) with filtering by contact, MIME type, and date range. Returns file metadata, not file contents.
list_contacts
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.
list_group_chats
List all group chats with member counts, message volumes, and activity dates. Group chats have multiple participants.
message_stats
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.
on_this_day
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.
resolve_contact
Fuzzy-match a name, phone number, or email to a contact record. Uses multi-level resolution: exact match, digits, fuzzy, and macOS AddressBook.
search_messages
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.
streaks
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.
temporal_heatmap
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.
who_initiates
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.
yearly_wrapped
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.
BEFORE YOU INSTALL
What to know first
Tools you get
25 tools when we connected. The documented set is 26, including check_new_messages, which did not show up in every session.
Requires
npx on PATH
Where it runs
All 7 documented clients run the server on your machine.
CONTEXT COST
Moderate Standing cost
Rated by the size of the 25 tool definitions that ride along on every turn, not by how many there are
INSTALLATION
Connect your client
Server setup
TERMINAL
npm install -g imessage-mcpMCP Clients
Claude Desktop, Claude Code, Cursor, Windsurf
JSON
{
"mcpServers": {
"imessage": {
"command": "npx",
"args": [
"-y",
"imessage-mcp"
]
}
}
}VS Code, GitHub Copilot in VS Code
JSON
{
"servers": {
"imessage": {
"command": "npx",
"args": [
"-y",
"imessage-mcp"
]
}
}
}Zed
ZED · JSON
{
"context_servers": {
"imessage": {
"command": {
"path": "npx",
"args": [
"-y",
"imessage-mcp"
]
}
}
}
}
