# iMessage MCP (npm · imessage-mcp)

25 tools for searching, analyzing, and exploring your iMessage history on macOS.

- Trust score: 69/100 (medium)
- Change this week: +23
- Registry status: active
- Liveness: live
- Owner verified: no
- Last scored: 2026-08-03

## Components

- npm · `imessage-mcp`: 69/100 (this document), [markdown](https://verifymcp.io/servers/anipotts-imessage-mcp/imessage-mcp.md), [page](https://verifymcp.io/servers/anipotts-imessage-mcp/imessage-mcp)

## Channel facts

- Registry: `npm`
- Package: `imessage-mcp`
- Version: `1.2.1`
- Transport: `stdio`

## Trust breakdown

How this component scores in each security and reliability category. Every signal is checked automatically from public evidence about the published package, including repeated runs of it in an isolated sandbox, and we only credit what we can confirm. Scores are 0–100 per category. Scoring method: https://verifymcp.io/docs/scoring (what has changed: https://verifymcp.io/docs/scoring/changelog)

Scored 2026-08-03.

- **Supply Chain Security**: 87/100
  - No malware found by supply-chain analysis.
  - Only part of the dependency tree could be resolved (130 of 134), so this covers what we could see, not the whole tree.
  - No install/post-install scripts declared.
  - Only part of the dependency tree could be resolved (130 of 134), so this covers what we could see, not the whole tree.
- **Provenance & Transparency**: 45/100
  - Source repository is publicly reachable at the declared URL.
  - Provenance check failed: no build-provenance attestation is published.
  - Clear OSI-approved license (MIT).
  - Actively maintained (last published 159 days ago).
  - Disclosure check failed: no security disclosure policy was found in the source repository.
- **Schema Quality & AI Usability**: 74/100
  - AI-judged instruction clarity (excellent).
  - Context-footprint check failed: tool/resource definitions use about 2887 tokens (~115/item across 25 items; 25 tools + 0 resources), over budget; trim descriptions and params.
  - Usage-examples check failed: none of the tools include examples.
- **Stability & Change Management**: 27/100
  - Stability observed for 8 of 30 days with no destabilising changes; credit accrues until the full window elapses.
- **Tool Coverage**: 100/100
  - 100% of tools have a non-trivial description (not blank, and not just the tool's name).
  - 100% of tool parameters carry a description.
- **Capabilities**: 100/100
  - Implements a supported MCP spec version (2025-11-25); the latest is 2026-07-28.

## Install

### Claude

```bash
claude mcp add anipotts-imessage-mcp -- npx -y imessage-mcp
```

### Codex

```bash
codex mcp add anipotts-imessage-mcp -- npx -y imessage-mcp
```

### opencode

```json
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "anipotts-imessage-mcp": {
      "type": "local",
      "command": [
        "npx",
        "-y",
        "imessage-mcp"
      ],
      "enabled": true
    }
  }
}
```

### OpenClaw

```bash
openclaw mcp add anipotts-imessage-mcp --command npx --arg -y --arg imessage-mcp
```

### Hermes

```yaml
mcp_servers:
  anipotts-imessage-mcp:
    command: "npx"
    args: ["-y", "imessage-mcp"]
```

### Other

```json
{
  "mcpServers": {
    "anipotts-imessage-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "imessage-mcp"
      ]
    }
  }
}
```

## Changelog

Every change recorded for this component, newest first. Days that predate change tracking, or that we cannot explain, say so: "we were watching and nothing happened" and "we were not watching" are different claims.

### 2026-08-03 (score 69, +1)

No change was recorded against any check on this day. Stability & Change Management went from 23 to 27. That category is still filling its 30-day observation window: 7 days of observed history at the previous scan, 8 at this one. The score rises as the window fills, whether or not the server changes.

### 2026-08-02 (score 68, +10)

- [security regression] Provenance: fail → unverified
- [security regression] Install scripts: pass → unverified
- [security improvement] Known CVEs: unverified → partial
- [functional regression] Maintenance: pass → unverified
- [functional regression] License: pass → unverified
- [functional improvement] Dependency health: unverified → partial
- [functional improvement] Stability: unverified → 0.23
- [functional] Licence: MIT

### 2026-08-01 (score 58, −10)

- [security regression] Known CVEs: partial → unverified
- [functional regression] Dependency health: partial → unverified

### 2026-07-31 (score 68, +53)

- [functional] We updated how we score, so this day's move reflects our rubric, not a change to the server

### 2026-07-30 (score 15, −64)

- [security regression] Known CVEs: partial → unverified
- [security regression] Malware scan: pass → unverified
- [functional regression] Dependency health: partial → unverified
- [functional regression] Tool coverage: 100 → unverified

### 2026-07-29 (score 79, +54)

- [security regression] Provenance: unverified → fail
- [security improvement] Known CVEs: unverified → partial
- [security improvement] Install scripts: unverified → pass
- [functional improvement] Maintenance: unverified → pass
- [functional improvement] License: unverified → pass
- [functional improvement] Tool coverage: unverified → 100
- [functional improvement] Schema quality: unverified → excellent
- [functional] Licence: MIT

### 2026-07-28 (score 25, −21)

- [functional regression] Tool coverage: 100 → unverified
- [functional improvement] Dependency health: unverified → partial
- [functional] First check of Schema quality: unverified

### 2026-07-27 (score 46)

First indexed and scored.

## MCP tools (25)

### `search_messages` (~236 tokens)

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.

Input parameters:

- `contact` (string): Filter by contact handle (phone/email) or name
- `date_from` (string): Start date (ISO format, e.g. 2024-01-01)
- `date_to`: End date (ISO format, e.g. 2024-12-31)
- `group_chat` (string): Filter by group chat name or chat_identifier
- `has_attachment` (boolean): Only messages with attachments
- `include_all` (boolean): Include messages from all contacts, even those you've never replied to (default: false)
- `limit` (number): Max results (default 50, max 500)
- `offset` (number): Pagination offset
- `query` (string): Text to search for (case-insensitive substring match)
- `received_only` (boolean): Only messages received
- `sent_only` (boolean): Only messages sent by you

### `get_conversation` (~124 tokens)

Get a full conversation thread with a specific contact or chat. Supports cursor-based pagination via before_rowid for scrolling through history.

Input parameters:

- `before_rowid` (number): Cursor: only messages before this ROWID (for pagination)
- `chat_id` (string): Chat identifier (e.g. chat123456789)
- `contact` (string): Contact handle (phone/email) or name
- `date_from` (string): Start date filter
- `date_to`: End date filter
- `limit` (number): Max messages (default 50, max 500)

### `list_contacts` (~128 tokens)

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.

Input parameters:

- `include_all` (boolean): Include messages from all contacts, even those you've never replied to (default: false)
- `limit` (number): Max results (default 50, max 500)
- `min_messages` (number): Minimum message count to include
- `sort_by` (string): Sort order (default: messages)
- `tier` (string): Filter by contact tier

### `get_contact` (~43 tokens)

Deep info on a specific contact: tier, message stats, yearly breakdown, and recent messages.

Input parameters:

- `contact` (string, required): Contact handle (phone/email) or name fragment

### `resolve_contact` (~58 tokens)

Fuzzy-match a name, phone number, or email to a contact record. Uses multi-level resolution: exact match, digits, fuzzy, and macOS AddressBook.

Input parameters:

- `query` (string, required): Name, phone number, or email to resolve

### `message_stats` (~124 tokens)

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.

Input parameters:

- `contact` (string): Filter by contact handle
- `date_from` (string): Start date (ISO)
- `date_to`: End date (ISO)
- `group_by` (string): Time grouping (default: month)
- `include_all` (boolean): Include messages from all contacts, even those you've never replied to (default: false)

### `contact_stats` (~57 tokens)

Deep per-contact analytics: message volumes, response time estimates, conversation patterns, and yearly trends.

Input parameters:

- `contact` (string, required): Contact handle or name fragment
- `date_from` (string): Start date
- `date_to`: End date

### `temporal_heatmap` (~113 tokens)

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.

Input parameters:

- `contact` (string): Filter by contact handle
- `date_from` (string): Start date
- `date_to`: End date
- `include_all` (boolean): Include messages from all contacts, even those you've never replied to (default: false)
- `sent_only` (boolean): Only your messages

### `list_group_chats` (~75 tokens)

List all group chats with member counts, message volumes, and activity dates. Group chats have multiple participants.

Input parameters:

- `limit` (number): Max results (default 50, max 500)
- `min_messages` (number): Minimum message count to include
- `sort_by` (string): Sort order (default: messages)

### `get_group_chat` (~65 tokens)

Detailed info on a specific group chat: all members with per-member message counts, activity timeline, and recent messages.

Input parameters:

- `chat_id` (string): Chat identifier (e.g. chat123456789)
- `name` (string): Group chat display name (fuzzy match)

### `list_attachments` (~125 tokens)

Query message attachments (images, videos, audio, documents) with filtering by contact, MIME type, and date range. Returns file metadata, not file contents.

Input parameters:

- `contact` (string): Filter by contact handle
- `date_from` (string): Start date (ISO)
- `date_to`: End date (ISO)
- `limit` (number): Max results (default 50, max 500)
- `mime_type` (string): Filter by MIME type prefix (e.g. 'image/', 'video/', 'audio/')
- `offset` (number): Pagination offset

### `get_reactions` (~131 tokens)

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.

Input parameters:

- `contact` (string): Filter by contact handle or name
- `date_from` (string): Start date (ISO)
- `date_to`: End date (ISO)
- `limit` (number): Max results for top lists (default 20)
- `reaction_type` (string): Filter by specific reaction type
- `sent_only` (boolean): Only reactions sent by you

### `get_read_receipts` (~91 tokens)

Read receipt and delivery timing analytics: per-contact read latency stats, unread patterns, fastest/slowest readers. Queries date_read and date_delivered columns.

Input parameters:

- `contact` (string): Filter by contact handle or name
- `date_from` (string): Start date (ISO)
- `date_to`: End date (ISO)
- `limit` (number): Max contacts to show (default 20)

### `get_thread` (~84 tokens)

Reconstruct iMessage reply threads using thread_originator_guid. Returns nested thread trees with parent message and all replies in order.

Input parameters:

- `contact` (string): Filter by contact handle or name -- shows threads from conversations with this contact
- `limit` (number): Max threads to return (default 10)
- `message_guid` (string): GUID of the thread originator message

### `get_edited_messages` (~110 tokens)

Find edited and unsent (retracted) messages. Queries date_retracted and date_edited columns. Returns message list with timestamps and per-contact stats.

Input parameters:

- `contact` (string): Filter by contact handle or name
- `date_from` (string): Start date (ISO)
- `date_to`: End date (ISO)
- `limit` (number): Max results (default 50, max 500)
- `type` (string): Type of edit to search for (default: both)

### `get_message_effects` (~97 tokens)

iMessage expressive send effects and screen effects analytics: slam, loud, gentle, invisible ink, confetti, fireworks, balloons, lasers, etc. Queries expressive_send_style_id.

Input parameters:

- `contact` (string): Filter by contact handle or name
- `date_from` (string): Start date (ISO)
- `date_to`: End date (ISO)
- `limit` (number): Max results for detail lists (default 20)

### `on_this_day` (~160 tokens)

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.

Input parameters:

- `contact` (string): Filter by contact handle or name
- `date` (string): Date to look up (ISO format, default: today)
- `include_all` (boolean): Include messages from all contacts, even those you've never replied to (default: false)
- `limit` (number): Max messages per year (default 5)
- `month_day` (string): Month-day to look up (MM-DD format, e.g. '12-25' for Christmas). Defaults to today.

### `first_last_message` (~71 tokens)

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?'

Input parameters:

- `contact` (string, required): Contact handle (phone/email) or name

### `who_initiates` (~173 tokens)

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.

Input parameters:

- `contact` (string): Filter by contact (omit for global ranking)
- `date_from` (string): Start date (ISO)
- `date_to`: End date (ISO)
- `gap_hours` (number): Hours of silence before a new conversation (default: 8)
- `include_all` (boolean): Include messages from all contacts, even those you've never replied to (default: false)
- `limit` (number): Max contacts to show (default 20)
- `min_conversations` (number): Minimum conversations to include contact (default: 5)

### `streaks` (~124 tokens)

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.

Input parameters:

- `contact` (string): Filter by contact (omit for top streaks across all contacts)
- `include_all` (boolean): Include messages from all contacts, even those you've never replied to (default: false)
- `limit` (number): Max contacts (default 20)
- `min_streak` (number): Minimum streak length in days (default: 3)

### `double_texts` (~134 tokens)

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.

Input parameters:

- `contact` (string): Contact handle or name (omit for global double-text ranking)
- `date_from` (string): Start date (ISO)
- `date_to`: End date (ISO)
- `limit` (number): Max burst results (default 20)
- `min_consecutive` (number): Minimum consecutive messages to count (default: 2)

### `conversation_gaps` (~93 tokens)

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.

Input parameters:

- `contact` (string, required): Contact handle or name
- `limit` (number): Max gaps to return (default 10)
- `min_gap_days` (number): Minimum gap in days to include (default: 7)

### `forgotten_contacts` (~124 tokens)

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.

Input parameters:

- `inactive_days` (number): Days of inactivity to count as 'forgotten' (default: 365)
- `include_all` (boolean): Include messages from all contacts, even those you've never replied to (default: false)
- `limit` (number): Max results (default 20)
- `min_messages` (number): Minimum past messages to qualify (default: 10)

### `yearly_wrapped` (~115 tokens)

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.

Input parameters:

- `include_all` (boolean): Include messages from all contacts, even those you've never replied to (default: false)
- `year` (number): Year to summarize (default: last year)

### `help` (~31 tokens)

Show the imessage-mcp guide: all 25 tools and usage examples. Call this when you're unsure what's available.

## Diagnostics

Captured diagnostic sections: Provenance, Dependencies. The full working is on the page: https://verifymcp.io/servers/anipotts-imessage-mcp/imessage-mcp#diagnostics

## Score history

- 2026-08-03: 69
- 2026-08-02: 68
- 2026-08-01: 58
- 2026-07-31: 68
- 2026-07-30: 15
- 2026-07-29: 79
- 2026-07-28: 25
- 2026-07-27: 46

## Links

- npm package: https://www.npmjs.com/package/imessage-mcp
- Socket report: https://socket.dev/npm/package/imessage-mcp
- Repository: https://github.com/anipotts/imessage-mcp
- Changelog RSS feed: https://verifymcp.io/servers/anipotts-imessage-mcp/imessage-mcp/changelog.xml
- Changelog JSON feed: https://verifymcp.io/servers/anipotts-imessage-mcp/imessage-mcp/changelog.json
- HTML version of this page: https://verifymcp.io/servers/anipotts-imessage-mcp/imessage-mcp