iMessage History

io.github.anipottsbuildsPublished by GitHub account anipottsbuildsv3.3.2Updated Oct 24, 2026

Read-only MCP server for searching and reading Apple Messages history on macOS.

VerifiedSTDIODesktop onlyFiles & StorageCommunication & Collaboration

Overview

AI-generated overview

A read-only local MCP server that lets an assistant search and read Apple Messages history on a Mac, including conversations, attachments and communicationstats

What you can do
Search messages by words, exact text, token or phrase, filtered by service, direction and date, and list conversations by contact, service, kind, reply state or date with their latest message. Read whole conversations with edits, unsent messages, reactions, replies, read receipts, group events and attachments, paging back through older events. Show one attachment, with images returned as JPEGs stripped of location and camera metadata. Pull changes since a cursor, including new, edited, unsent and deleted messages, memberships, reactions and receipts. Analyze counts by hour and weekday, response times, streaks and who starts conversations, and resolve a name, phone number or email to a Mac's-
When to use it
Useful when you want an assistant to catch you up on texts, find a specific message, summarize a week of conversations, or answer questions about reply speed and messaging habits, all on a Mac with the Messages app. It suits users who want local, read-only access rather than a cloud service.
Requirements
macOS 14 or newer and Node.js 24.16 or newer for npx installs (Claude Desktop bundles its own). The app running the server needs Full Disk Access to the Messages database. Optional settings include IMESSAGE_PRIVACY, IMESSAGE_CONTACTS, IMESSAGE_DB, IMESSAGE_CACHE and IMESSAGE_UPDATE_CHECK; HTTP transport additionally needs IMESSAGE_API_TOKEN or IMESSAGE_API_TOKEN_FILE.
Before you install
Message content is sent to whichever MCP client and model provider you use, under their policies; the default full privacy mode exposes message text and filenames, so redacted or aggregate modes limit what leaves the server. Message text is untrusted and may contain attempts to manipulate the assistant. The server is read-only and cannot send, edit or react, but it reads your entire Messages history and Contacts. The only network request is an optional npm version check.

Installation

In SourceWeft

  1. Open iMessage History in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.

Other MCP clients

Follow the launch instructions in the repository.

README

[Image]

imessage-mcp

[npm] [MCP Registry] [CI] [License: MIT]

Search and read your Messages history from Claude, Codex, Cursor, VS Code, and any other MCP client.

[Claude Code catching up on a real conversation about a hackathon through imessage-mcp]

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:

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
bash
amp mcp add imessage -- npx -y imessage-mcp@latest
Claude Code
bash
claude mcp add --scope user imessage -- npx -y imessage-mcp@latest

Or install the plugin: /plugin marketplace add anipotts/imessage-mcp, then /plugin install imessage-mcp@anipotts.

Claude Desktop

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.

Cline

Add the standard config to cline_mcp_settings.json (docs).

Codex
bash
codex mcp add imessage -- npx -y imessage-mcp@latest

Or in ~/.codex/config.toml:

toml
[mcp_servers.imessage]command = "npx"args = ["-y", "imessage-mcp@latest"]
Copilot CLI

Run /mcp add, or add the standard config to ~/.copilot/mcp-config.json with "type": "local".

Cursor

[Install in Cursor]

Or add the standard config to ~/.cursor/mcp.json.

Gemini CLI

Add the standard config to ~/.gemini/settings.json.

Goose

[Install in Goose]

JetBrains (Junie)

Add the standard config to .junie/mcp/mcp.json, or type /mcp in Junie CLI.

Kiro

[Add to Kiro]

opencode

In ~/.config/opencode/opencode.json:

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

[Install in VS Code] [Install in VS Code Insiders]

bash
code --add-mcp '{"name":"imessage","command":"npx","args":["-y","imessage-mcp@latest"]}'
Warp, Windsurf, Zed, and others

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.

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:

promptwhat it does
catch_upWho is waiting on a reply from you, and what they need
draft_replyA reply in your own texting style. You send it; this server cannot.
recapYour week in messages: volume, busiest conversations, anyone still waiting

Clients that attach resources can use imessage://conversations and imessage://conversations/{chat_id}.

Tools

toolwhat it does
search_messagesSearch 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
get_conversationRead a conversation by chat_id or by a contact or group name, with edits, reactions, receipts, replies, group events, and attachments. The cursor pages to older events
list_conversationsFind conversations by contact, service, kind, reply state, or date, each with its latest message, newest first or by who you text most
get_attachmentShow one attachment from get_conversation: images as a JPEG with location and camera metadata removed, text files as text. Needs the full privacy mode
sync_messagesPull every change since a cursor: new, edited, unsent, and deleted messages, conversation memberships, reactions, and receipts
analyze_communicationMessage counts by hour and weekday, response times, streaks, and who starts conversations
resolve_contactMatch a name, phone number, or email to a contact in your Mac's Address Book, and report ambiguity rather than guess
server_statusVersion, 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.

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"].

optiondescription
--privacy <mode>The most any caller can see. full (default), redacted (names and masked handles, calendar days, no message text or filenames), or aggregate (counts only). A call can ask for a stricter mode, never a looser one. env IMESSAGE_PRIVACY
--contacts <mode>live (default) names handles from your Contacts; none shows handles only. env IMESSAGE_CONTACTS
--database <path>Read a copy of chat.db instead of this Mac's Messages. env IMESSAGE_DB
--transport http --port <n>Serve MCP over HTTP on 127.0.0.1 instead of stdio. Requires IMESSAGE_API_TOKEN or IMESSAGE_API_TOKEN_FILE. IMESSAGE_ALLOWED_HOSTS and IMESSAGE_ALLOWED_ORIGINS take comma-separated lists; both default to localhost.
IMESSAGE_CACHE=0Keep the search index in memory only
IMESSAGE_WARM_SEARCH=0Build the search index on the first search instead of at startup
IMESSAGE_UPDATE_CHECK=0Turn 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 redacted or aggregate limits 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_status reports 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

bash
npm cinpm test      # unit tests on synthetic Messages databasesnpm run e2e   # launches the built server over stdio and HTTPnpm run perf  # one-million-message performance gates

Tests 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

Source: README.md at commit a1550ec

Tools

0
SourceWeft started this package once in an isolated sandbox, without credentials, to list its tools. That failed: the package did not install.

Version history

1
  1. v3.3.2LatestOct 24, 2026

Score

50% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 days25 pts

    Keep the endpoint answering the MCP handshake; SourceWeft probes it every 30 days.

  • Auth declared10 pts

    Declare the credential headers in the registry entry, or keep the endpoint answering the probe so its auth can be classified.

  • Tools listed15 pts

    Answer tools/list without a credential, or ship a package that starts in a sandbox without one.

  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts