iMessage MCP
NPM · IMESSAGE-MCP · SCANNED AUG 3
25 tools for searching, analyzing, and exploring your iMessage history on macOS.
Available components
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. How we score →
Supply Chain Security87
- No malware found by supply-chain analysis.Pass
- Only part of the dependency tree could be resolved (130 of 134), so this covers what we could see, not the whole tree.Partial
- No install/post-install scripts declared.Pass
- Only part of the dependency tree could be resolved (130 of 134), so this covers what we could see, not the whole tree. View diagnostics → Partial
Provenance & Transparency45
- Source repository is publicly reachable at the declared URL. View diagnostics → Pass
- Provenance check failed: no build-provenance attestation is published. See how to fix → View diagnostics → Fail
- Clear OSI-approved license (MIT).Pass
- Actively maintained (last published 159 days ago).Pass
- Disclosure check failed: no security disclosure policy was found in the source repository. See how to fix → Fail
Schema Quality & AI Usability74
- AI-judged instruction clarity (excellent).Pass
- 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. See how to fix → Fail
- Usage-examples check failed: none of the tools include examples. See how to fix → Fail
Stability & Change Management27
- Stability observed for 8 of 30 days with no destabilising changes; credit accrues until the full window elapses.Partial
Tool Coverage100
- 100% of tools have a non-trivial description (not blank, and not just the tool's name).Pass
- 100% of tool parameters carry a description.Pass
Capabilities100
- Implements a supported MCP spec version (2025-11-25); the latest is 2026-07-28.Pass
Add this component to your MCP client. Where a client-specific snippet is available, pick your client below and copy it straight into your config; otherwise use the connection detail shown.
npm · imessage-mcp
claude mcp add anipotts-imessage-mcp -- npx -y imessage-mcp
codex mcp add anipotts-imessage-mcp -- npx -y imessage-mcp
{
"$schema": "https://opencode.ai/config.json",
"mcp": {
"anipotts-imessage-mcp": {
"type": "local",
"command": [
"npx",
"-y",
"imessage-mcp"
],
"enabled": true
}
}
} openclaw mcp add anipotts-imessage-mcp --command npx --arg -y --arg imessage-mcp
mcp_servers:
anipotts-imessage-mcp:
command: "npx"
args: ["-y", "imessage-mcp"] {
"mcpServers": {
"anipotts-imessage-mcp": {
"command": "npx",
"args": [
"-y",
"imessage-mcp"
]
}
}
} Every change we have recorded for this component, newest first. Security-relevant changes are always shown. ▲ marks a change for the better, ▼ a change for the worse; unmarked changes are neutral.
- 3 Aug 26 +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.
- 2 Aug 26 +10
- Provenance: fail → unverified ▼ security
- Install scripts: pass → unverified ▼ security
- Known CVEs: unverified → partial ▲ security
- Maintenance: pass → unverified ▼ functional
- License: pass → unverified ▼ functional
- Dependency health: unverified → partial ▲ functional
- Stability: unverified → 0.23 ▲ functional
- Licence: MIT functional
- 1 Aug 26 −10
- Known CVEs: partial → unverified ▼ security
- Dependency health: partial → unverified ▼ functional
- 31 Jul 26 +53
- We updated how we score, so this day's move reflects our rubric, not a change to the server See what changed → functional
- 30 Jul 26 −64
- Known CVEs: partial → unverified ▼ security
- Malware scan: pass → unverified ▼ security
- Dependency health: partial → unverified ▼ functional
- Tool coverage: 100 → unverified ▼ functional
- 29 Jul 26 +54
- Provenance: unverified → fail ▼ security
- Known CVEs: unverified → partial ▲ security
- Install scripts: unverified → pass ▲ security
- Maintenance: unverified → pass ▲ functional
- License: unverified → pass ▲ functional
- Tool coverage: unverified → 100 ▲ functional
- Schema quality: unverified → excellent ▲ functional
- Licence: MIT functional
- 28 Jul 26 −21
- Tool coverage: 100 → unverified ▼ functional
- Dependency health: unverified → partial ▲ functional
- First check of Schema quality: unverified functional
- 27 Jul 26 46
First indexed and scored.
Diagnostic detail from the automated scan of this channel: what the scanner observed at each step, so you can see exactly where a check passed or failed. It is informational only and never changes the trust score.
Captured 3 Aug 2026 · Analysed npm/[email protected]
Provenance none
Ecosystem: npm · Outcome: none
Dependencies 130 packages
130 packages in the resolved dependency tree · 130 deprecated · 49 stale.
The dependency tree was only partially resolved, so these counts may be incomplete.
The tools this component advertises to a client, with an estimated token cost for each. Expand a tool to see its parameters and schema. The per-tool counts are indicative and are not scored directly; the schema's total context footprint is one signal in Schema Quality & AI Usability.
contact_stats ~57
Deep per-contact analytics: message volumes, response time estimates, conversation patterns, and yearly trends.
| Name | Type | Req | Description |
|---|---|---|---|
| contact | string | yes | Contact handle or name fragment |
| date_from | string | — | Start date |
| date_to | — | — | End date |
No output schema declared.
No examples provided.
conversation_gaps ~93
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.
| Name | Type | Req | Description |
|---|---|---|---|
| contact | string | yes | Contact handle or name |
| limit | number | — | Max gaps to return (default 10) |
| min_gap_days | number | — | Minimum gap in days to include (default: 7) |
No output schema declared.
No examples provided.
double_texts ~134
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.
| Name | Type | Req | Description |
|---|---|---|---|
| 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) |
No output schema declared.
No examples provided.
first_last_message ~71
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?'
| Name | Type | Req | Description |
|---|---|---|---|
| contact | string | yes | Contact handle (phone/email) or name |
No output schema declared.
No examples provided.
forgotten_contacts ~124
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.
| Name | Type | Req | Description |
|---|---|---|---|
| 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) |
No output schema declared.
No examples provided.
get_contact ~43
Deep info on a specific contact: tier, message stats, yearly breakdown, and recent messages.
| Name | Type | Req | Description |
|---|---|---|---|
| contact | string | yes | Contact handle (phone/email) or name fragment |
No output schema declared.
No examples provided.
get_conversation ~124
Get a full conversation thread with a specific contact or chat. Supports cursor-based pagination via before_rowid for scrolling through history.
| Name | Type | Req | Description |
|---|---|---|---|
| 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) |
No output schema declared.
No examples provided.
get_edited_messages ~110
Find edited and unsent (retracted) messages. Queries date_retracted and date_edited columns. Returns message list with timestamps and per-contact stats.
| Name | Type | Req | Description |
|---|---|---|---|
| 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) |
No output schema declared.
No examples provided.
get_group_chat ~65
Detailed info on a specific group chat: all members with per-member message counts, activity timeline, and recent messages.
| Name | Type | Req | Description |
|---|---|---|---|
| chat_id | string | — | Chat identifier (e.g. chat123456789) |
| name | string | — | Group chat display name (fuzzy match) |
No output schema declared.
No examples provided.
get_message_effects ~97
iMessage expressive send effects and screen effects analytics: slam, loud, gentle, invisible ink, confetti, fireworks, balloons, lasers, etc. Queries expressive_send_style_id.
| Name | Type | Req | Description |
|---|---|---|---|
| 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) |
No output schema declared.
No examples provided.
get_reactions ~131
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.
| Name | Type | Req | Description |
|---|---|---|---|
| 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 |
No output schema declared.
No examples provided.
get_read_receipts ~91
Read receipt and delivery timing analytics: per-contact read latency stats, unread patterns, fastest/slowest readers. Queries date_read and date_delivered columns.
| Name | Type | Req | Description |
|---|---|---|---|
| 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) |
No output schema declared.
No examples provided.
get_thread ~84
Reconstruct iMessage reply threads using thread_originator_guid. Returns nested thread trees with parent message and all replies in order.
| Name | Type | Req | Description |
|---|---|---|---|
| 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 |
No output schema declared.
No examples provided.
help ~31
Show the imessage-mcp guide: all 25 tools and usage examples. Call this when you're unsure what's available.
Input schema present but exposes no named parameters.
No output schema declared.
No examples provided.
list_attachments ~125
Query message attachments (images, videos, audio, documents) with filtering by contact, MIME type, and date range. Returns file metadata, not file contents.
| Name | Type | Req | Description |
|---|---|---|---|
| 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 |
No output schema declared.
No examples provided.
list_contacts ~128
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.
| Name | Type | Req | Description |
|---|---|---|---|
| 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 |
No output schema declared.
No examples provided.
list_group_chats ~75
List all group chats with member counts, message volumes, and activity dates. Group chats have multiple participants.
| Name | Type | Req | Description |
|---|---|---|---|
| limit | number | — | Max results (default 50, max 500) |
| min_messages | number | — | Minimum message count to include |
| sort_by | string | — | Sort order (default: messages) |
No output schema declared.
No examples provided.
message_stats ~124
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.
| Name | Type | Req | Description |
|---|---|---|---|
| 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) |
No output schema declared.
No examples provided.
on_this_day ~160
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.
| Name | Type | Req | Description |
|---|---|---|---|
| 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. |
No output schema declared.
No examples provided.
resolve_contact ~58
Fuzzy-match a name, phone number, or email to a contact record. Uses multi-level resolution: exact match, digits, fuzzy, and macOS AddressBook.
| Name | Type | Req | Description |
|---|---|---|---|
| query | string | yes | Name, phone number, or email to resolve |
No output schema declared.
No examples provided.
search_messages ~236
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.
| Name | Type | Req | Description |
|---|---|---|---|
| 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 |
No output schema declared.
No examples provided.
streaks ~124
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.
| Name | Type | Req | Description |
|---|---|---|---|
| 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) |
No output schema declared.
No examples provided.
temporal_heatmap ~113
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.
| Name | Type | Req | Description |
|---|---|---|---|
| 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 |
No output schema declared.
No examples provided.
who_initiates ~173
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.
| Name | Type | Req | Description |
|---|---|---|---|
| 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) |
No output schema declared.
No examples provided.
yearly_wrapped ~115
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.
| Name | Type | Req | Description |
|---|---|---|---|
| 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) |
No output schema declared.
No examples provided.