# imessage-mcp iMessage MCP server — 25 tools for searching, analyzing, and exploring your entire iMessage history on macOS - **Type:** MCP server - **Trust:** 85/100 (A), scored on the package rubric - **Verification:** verified (build provenance) - **Version:** 1.3.1 - **Author:** Ani Potts - **License:** MIT - **npm:** imessage-mcp - **Source:** https://github.com/anipotts/imessage-mcp - **Compatible clients:** claude-code, cursor, copilot, gemini (basis: transport) ## Trust 85/100 (A), scored on the package rubric - Publisher verified: no - Build provenance: verified attestation - npm trusted publishing (OIDC): yes - Install scripts: nothing suspicious found - Prompt-injection scan: not run - Obfuscation scan: not run - Evidence age: 2 days ## Security scan - **Status:** clean - **Scanned:** 2026-08-31T13:40:44.001Z - **Version scanned:** 1.3.1 - **CVEs:** none found by OSV at scan time ## Tools 25 declared. Statically extracted from the shipped source — a floor on the surface, not a census. - `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 - `contact_stats` — Deep per-contact analytics: message volumes, response time estimates, conversation patterns, and yearly trends. - `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 - `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 act - `get_contact` — Deep info on a specific contact: tier, message stats, yearly breakdown, and recent messages. - `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. - `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_message_effects` — iMessage expressive send effects and screen effects analytics: slam, loud, gentle, invisible ink, confetti, fireworks, balloons, lasers, etc. Queries expressive - `list_group_chats` — List all group chats with member counts, message volumes, and activity dates. Group chats have multiple participants. - `get_group_chat` — Detailed info on a specific group chat: all members with per-member message counts, activity timeline, and recent messages. - `help` — Show the imessage-mcp guide: all 25 tools and usage examples. Call this when you're unsure what's available. - `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. - `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 - `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, - `get_conversation` — Get a full conversation thread with a specific contact or chat. Supports cursor-based pagination via before_rowid for scrolling through history. - `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. Answer - `streaks` — Consecutive-day messaging streaks with contacts. Like Snapchat streaks but for iMessage. Shows longest streak, when it happened, and current streak status. By d - `double_texts` — Detect double-texting and unanswered message patterns. Finds when you (or a contact) sent multiple consecutive messages without a reply. Shows frequency, longes - `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 - `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 de - `get_reactions` — Tapback/reaction analytics: distribution by type, top reactors, most-reacted messages, emoji breakdown. Queries associated_message_type 2000-2005 for love/like/ - `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 colum - `get_thread` — Reconstruct iMessage reply threads using thread_originator_guid. Returns nested thread trees with parent message and all replies in order. - `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 tr ## Install **Verdict: install** — No blocking findings and no open coverage gaps — safe to install as configured. **Config** (claude-code): ```json "{\n \"mcpServers\": {\n \"imessage\": {\n \"command\": \"npx\",\n \"args\": [\n \"-y\",\n \"imessage-mcp\"\n ]\n }\n }\n}" ``` ## Blast radius Contained to moderate — no credential declaration found, from the publisher, the upstream registry, or the README. Known so far: runs on your machine; read-only tool surface. - Floor 13, ceiling 31 (tier: unknown) - `unknown` means the floor and ceiling land in different bands — not measured enough to name one. It does not mean low. - This is impact, not likelihood. A high radius is not a defect: a filesystem server is supposed to write files. It is never part of the trust score. ## Machine-readable views of this entry - Signed JSON: https://forgeregistry.com/api/v1/packages/imessage-mcp - Install plan: https://forgeregistry.com/api/v1/packages/imessage-mcp/install-plan - Alternatives: https://forgeregistry.com/api/v1/alternatives/imessage-mcp - HTML page: https://forgeregistry.com/registry/imessage-mcp - MCP: POST https://forgeregistry.com/api/mcp → `forge_get_package` / `forge_install_plan` ## About this document Generated by Forge (https://forgeregistry.com) — a compact rendering of the same record served, signed, at the JSON URL above. Trust and scan facts are the registry's own measurements; anything Forge did not measure is named as unmeasured rather than omitted.