# Imessage Mcp > Tools for securely exploring your iMessage history with AI. Spotify Wrapped for texts, conversation analytics, search, streaks, and more. Read-only MCP server for macOS. - **Type:** MCP server - **Install:** `agentstack add mcp-anipotts-imessage-mcp` - **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior - **Seller:** [anipotts](https://agentstack.voostack.com/s/anipotts) - **Installs:** 0 - **Category:** [Databases](https://agentstack.voostack.com/c/databases) - **Latest version:** 0.1.0 - **License:** MIT - **Upstream author:** [anipotts](https://github.com/anipotts) - **Source:** https://github.com/anipotts/imessage-mcp - **Website:** https://npmjs.com/package/imessage-mcp ## Install ```sh agentstack add mcp-anipotts-imessage-mcp ``` Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent. ## About # imessage-mcp [](https://www.npmjs.com/package/imessage-mcp) [](https://opensource.org/licenses/MIT) [](https://www.typescriptlang.org/) [](https://modelcontextprotocol.io) [](https://github.com/anipotts/imessage-mcp/actions/workflows/ci.yml) [](https://nodejs.org) **26 tools for locally exploring your iMessage history with AI.** > if this helped you, star it. it helps others find it. An [MCP server](https://modelcontextprotocol.io) that gives AI assistants **read-only** access to your local iMessage database. Nothing is written, modified, or uploaded. Your messages stay on your Mac; the AI only sees what you ask about. > **Read-only access to 2 local files** (`chat.db` + `AddressBook`). Zero network requests. Nothing is written, uploaded, or shared. All 26 tools are annotated `readOnlyHint: true` — your MCP client can auto-approve every call without prompts. ## Install ```bash npm install -g imessage-mcp ``` Or run without installing: ```bash npx imessage-mcp doctor ``` **[Smithery](https://smithery.ai):** One-click install via the Smithery registry — search for `imessage-mcp`. ### Add to your AI client ```bash # Claude Code (one command) claude mcp add imessage -- npx -y imessage-mcp ``` ```bash # Claude Desktop — add to ~/Library/Application Support/Claude/claude_desktop_config.json ``` ```json { "mcpServers": { "imessage": { "command": "npx", "args": ["-y", "imessage-mcp"] } } } ``` See [Setup](#setup) for Cursor, Windsurf, VS Code, Codex CLI, Cline, JetBrains, and Zed. ### Claude Code Plugin For slash commands and agents: ```bash claude plugin add anipotts/imessage-mcp ``` ### Prerequisites 1. **macOS** (iMessage is macOS-only) 2. **Node.js 18+** (`node --version`) 3. **Database access** for your host application — macOS protects `chat.db` with its Application Data permission. Grant access in: **System Settings > Privacy & Security > Full Disk Access** and enable the app running the MCP server (your terminal, Claude Desktop, or Cursor). GUI apps like Claude Desktop and Cursor may already have this permission. 4. **Messages in iCloud** enabled on your Mac (if you use multiple devices) — see [iCloud Sync & Multiple Devices](#icloud-sync--multiple-devices) ## Privacy & Security imessage-mcp reads your local iMessage database in **read-only mode**. No data leaves your machine. Nothing is written, modified, uploaded, or shared. | Path | Access | Purpose | | --- | --- | --- | | `~/Library/Messages/chat.db` | Read-only | Your iMessage database | | `~/Library/Application Support/AddressBook/` | Read-only | Contact name resolution | No other files are accessed. No external APIs are called. ``` chat.db --> [imessage-mcp] --> stdio/http --> [Your MCP Client] --> AI Provider ^ ^ Your Mac only Already authorized by you ``` ## What Can You Ask? Once connected, ask your AI assistant anything about your messages in plain language: - "Give me my 2024 iMessage Wrapped" - "Do I always text first with [name]?" - "What's my longest texting streak?" - "Who reacts to my messages the most?" - "What was the first text I ever sent my partner?" - "What was I texting about on this day last year?" - "Do I double-text [name] a lot?" - "Who have I lost touch with?" More examples - "Show me the longest silence between me and [name]" - "How many messages have I sent this year?" - "Show my conversation with Mom" - "What time of day am I most active texting?" - "Show me messages people unsent" - "What are the most popular group chats?" ## Tools 26 tools across 10 categories. All read-only. All annotated with `readOnlyHint: true`. | Tool | Description | | --- | --- | | `search_messages` | Full-text search with filters: query, contact, date range, direction, group chat, attachments | | `yearly_wrapped` | Spotify Wrapped for iMessage — full year summary | | `who_initiates` | Who starts conversations? Initiation ratio per contact | | `streaks` | Consecutive-day messaging streaks | | `get_reactions` | Tapback distribution, top reactors, most-reacted messages | | `on_this_day` | Messages from this date in past years | All 26 tools | Tool | Description | | --- | --- | | `search_messages` | Full-text search with filters: query, contact, date range, direction, group chat, attachments | | `get_conversation` | Conversation thread with cursor-based pagination | | `list_contacts` | All contacts with message counts and date ranges | | `get_contact` | Deep contact info with stats and yearly breakdown | | `resolve_contact` | Fuzzy-match a name, phone number, or email to a contact | | `message_stats` | Aggregate stats with time-series grouping | | `contact_stats` | Per-contact volumes, trends, and hourly patterns | | `temporal_heatmap` | 7x24 activity heatmap (day-of-week by hour) | | `on_this_day` | Messages from this date in past years | | `first_last_message` | First and last message ever exchanged with a contact | | `who_initiates` | Who starts conversations? Initiation ratio per contact | | `streaks` | Consecutive-day messaging streaks | | `double_texts` | Detect double-texting and unanswered message patterns | | `conversation_gaps` | Find the longest silences in a conversation | | `forgotten_contacts` | Contacts you've lost touch with | | `yearly_wrapped` | Spotify Wrapped for iMessage — full year summary | | `list_group_chats` | Group chats with member counts and activity | | `get_group_chat` | Per-member stats and monthly activity timeline | | `list_attachments` | Query attachments by contact, MIME type, and date range | | `get_reactions` | Tapback distribution, top reactors, most-reacted messages | | `get_read_receipts` | Read/delivery latency and unread patterns | | `get_thread` | Reconstruct reply thread trees | | `get_edited_messages` | Edited and unsent messages with timing | | `get_message_effects` | Slam, loud, confetti, fireworks analytics | | `check_new_messages` | Track new messages since your last check (baseline + delta) | | `help` | Full tool guide with usage examples | ## Setup ### Claude Desktop Add to `~/Library/Application Support/Claude/claude_desktop_config.json`: ```json { "mcpServers": { "imessage": { "command": "npx", "args": ["-y", "imessage-mcp"] } } } ``` Restart Claude Desktop after saving. ### Claude Code ```bash claude mcp add imessage -- npx -y imessage-mcp ``` Or add to `.mcp.json` in your project root: ```json { "mcpServers": { "imessage": { "command": "npx", "args": ["-y", "imessage-mcp"] } } } ``` OpenAI Codex CLI ```bash codex --mcp-config '{"imessage":{"command":"npx","args":["-y","imessage-mcp"]}}' ``` Or add to `~/.codex/config.json`: ```json { "mcpServers": { "imessage": { "command": "npx", "args": ["-y", "imessage-mcp"] } } } ``` Cursor Add to `~/.cursor/mcp.json`: ```json { "mcpServers": { "imessage": { "command": "npx", "args": ["-y", "imessage-mcp"] } } } ``` Windsurf Add to `~/.codeium/windsurf/mcp_config.json`: ```json { "mcpServers": { "imessage": { "command": "npx", "args": ["-y", "imessage-mcp"] } } } ``` VS Code (GitHub Copilot) Add to `.vscode/mcp.json` in your project root: **stdio (default):** ```json { "servers": { "imessage": { "command": "npx", "args": ["-y", "imessage-mcp"] } } } ``` **HTTP transport (remote / Docker):** ```json { "servers": { "imessage": { "type": "http", "url": "http://localhost:3000/mcp" } } } ``` Cline (VS Code) Add via the Cline MCP settings UI, or edit `cline_mcp_settings.json`: ```json { "mcpServers": { "imessage": { "command": "npx", "args": ["-y", "imessage-mcp"] } } } ``` JetBrains IDEs Settings > Tools > AI Assistant > MCP Servers > Add: - **Name:** `imessage` - **Command:** `npx` - **Args:** `-y imessage-mcp` Zed Add to `~/.config/zed/settings.json`: ```json { "context_servers": { "imessage": { "command": { "path": "npx", "args": ["-y", "imessage-mcp"] } } } } ``` ## CLI Commands imessage-mcp doctor — run setup diagnostics Checks macOS version, Node.js version, chat.db access, database permissions, AddressBook, and message count. ``` $ npx imessage-mcp doctor imessage-mcp doctor ✓ macOS: Running on macOS (darwin) ✓ Node.js: Node v22.0.0 (>= 18 required) ✓ chat.db: Found at /Users/you/Library/Messages/chat.db ✓ Database access: Database readable ✓ Messages: 97,432 messages indexed ✓ AddressBook: 342 contacts resolved All checks passed — ready to use! ``` Pass `--json` for machine-readable output: ```bash npx imessage-mcp doctor --json ``` imessage-mcp dump — export messages or contacts to JSON ```bash # Export last 1000 messages npx imessage-mcp dump > messages.json # Filter by contact npx imessage-mcp dump --contact "+15551234567" # Date range with custom limit npx imessage-mcp dump --from 2024-01-01 --to 2024-12-31 --limit 5000 # Export contacts (excluding spam/promo by default) npx imessage-mcp dump --contacts > contacts.json # Include all contacts (even ones you never replied to) npx imessage-mcp dump --contacts --all > all-contacts.json # Export all messages (including unfiltered contacts) npx imessage-mcp dump --all > all-messages.json ``` ## Transport Modes By default, imessage-mcp uses **stdio** transport — the standard for local MCP clients like Claude Desktop and Claude Code. For workflow tools (n8n, Lutra, Copilot Studio) or remote access, HTTP transport is available. | Flag | Short | Default | Description | | --- | --- | --- | --- | | `--transport` | `-t` | `stdio` | Transport mode: `stdio`, `http`, or `sse` | | `--port` | `-p` | `3000` | Port for HTTP/SSE transport | | `--host` | `-H` | `127.0.0.1` | Bind address (use `0.0.0.0` for Docker/remote) | Streamable HTTP (recommended for HTTP) ```bash npx imessage-mcp --transport http --port 3000 ``` Starts a Streamable HTTP server on `http://127.0.0.1:3000/mcp`. Supports `POST`, `GET`, and `DELETE` on `/mcp` with session management via `mcp-session-id` headers. This is the MCP 2025-03-26 standard. Legacy SSE (for older clients) ```bash npx imessage-mcp --transport sse --port 3000 ``` Starts a legacy SSE server: `GET /sse` to establish the stream, `POST /messages?sessionId=` for JSON-RPC requests. Use this only if your client does not support Streamable HTTP. ## Docker Run imessage-mcp as an HTTP server in Docker. Copy your `chat.db` to a volume mount: ```bash docker build -t imessage-mcp . docker run -p 3000:3000 -v /path/to/chat.db:/data/chat.db:ro imessage-mcp ``` The container starts with `--transport http --host 0.0.0.0` on port 3000 by default. Connect any MCP client to `http://localhost:3000/mcp`. To secure the HTTP endpoint with authentication: ```bash docker run -p 3000:3000 -e IMESSAGE_API_TOKEN=your-secret-token -v /path/to/chat.db:/data/chat.db:ro imessage-mcp ``` All requests must then include the `Authorization: Bearer your-secret-token` header. Safe Mode — redact all message bodies Prevent message bodies from being sent to the AI. Only metadata (counts, dates, contact names) is returned. No actual message text. ```json { "mcpServers": { "imessage": { "command": "npx", "args": ["-y", "imessage-mcp"], "env": { "IMESSAGE_SAFE_MODE": "1" } } } } ``` Useful for demos, shared environments, or when you want analytics without exposing private conversations. Smart Filtering — spam/promo exclusion By default, listing and global search tools only include contacts you have actually replied to. This filters out spam, promo texts, and unknown senders. **Filtered tools:** `search_messages` (global), `list_contacts`, `message_stats` (global), `temporal_heatmap` (global), `who_initiates` (global), `streaks` (global), `on_this_day` (global), `forgotten_contacts`, `yearly_wrapped`. **Unfiltered tools:** `get_conversation`, `get_contact`, `contact_stats`, `first_last_message`, `conversation_gaps`, `get_reactions`, `get_read_receipts`, `get_thread`, `get_edited_messages`, `get_message_effects`, group chats, attachments, `check_new_messages`. To include all contacts (including unrecognized senders), pass `include_all: true` to any filtered tool. Sync & New Messages — real-time notifications > **Looking for iCloud sync?** This section covers real-time message tracking within imessage-mcp. To sync your full message history from iPhone/iPad to your Mac, see [iCloud Sync & Multiple Devices](#icloud-sync--multiple-devices). By default, every query reads the latest data — if someone texts you, your next tool call sees it immediately. No sync needed. For proactive awareness, the `check_new_messages` tool tracks what arrived since your last check: 1. First call sets a baseline 2. Subsequent calls report the delta — count, who messaged, and optional text previews For push notifications (opt-in): ```json { "mcpServers": { "imessage": { "command": "npx", "args": ["-y", "imessage-mcp"], "env": { "IMESSAGE_SYNC": "watch" } } } } ``` This watches your iMessage database for changes and notifies your AI client within seconds. Uses macOS FSEvents — zero CPU when idle. ## Configuration | Variable | Default | Description | | --- | --- | --- | | `IMESSAGE_DB` | `~/Library/Messages/chat.db` | Path to iMessage database | | `IMESSAGE_SAFE_MODE` | `false` | Set to `1` to redact all message bodies | | `IMESSAGE_SYNC` | `off` | Sync mode: `off`, `watch` (FSEvents), or `poll:N` (every N seconds) | | `IMESSAGE_API_TOKEN` | _(none)_ | Bearer token for HTTP/SSE auth. If set, requests must include `Authorization: Bearer ` | iCloud Sync & Multiple Devices ### iCloud Sync & Multiple Devices imessage-mcp reads your Mac's local database (`~/Library/Messages/chat.db`). This database only contains messages that have been **synced to your Mac**. If your conversations live on your iPhone or iPad but haven't synced, imessage-mcp won't see them. > If you only use iMessage on your Mac, you can skip this — your messages are already in `chat.db`. ### How iMessage sync works Apple's "Messages in iCloud" keeps your full message history synchronized across all your Apple devices: ``` ┌─────────────┐ ┌──────────┐ ┌──────────────┐ │ iPhone/iPad │ ──────► │ iCloud │ ──────► │ Your Mac │ │ (sends & │ ◄────── │(Messages │ ◄────── │ │ │ receives) │ │in iCloud)│ │ chat.db │ └─────────────┘ └──────────┘ └──────┬───────┘ │ ▼ imessage-mcp reads this ↑ ``` Without "Messages in iCloud" enabled **on your Mac**, the Mac's `chat.db` only contains messages sent and received while Messages.app was actively running on that Mac. ### Setup #### 1. Enable on your Mac 1. Open **Messages.app** on your Mac 2. Go to **Settings** (Cmd+,) > **iMessage** tab 3. Check **"Enable Messages in iCloud"** 4. Keep Messages.app open — sync begins automatically #### 2. Enable on your iPhone/iPad 1. Open **Settings** > tap your **name** (Apple ID) > **iCloud** > **Messages** 2. Toggle **"Use on this iPhone"** ON #### 3. Same Apple ID on all devices All devices must be signed into the **same Apple ID**. Check: Mac (System Settings > Apple ID), iPhone (Settings > tap your name). #### 4. Wait for sync to complete Initial sync can take **hours or even days** for large message histories. During sync: - Messages.app must remain **open** on your Mac - Your Mac should be connected to **Wi-Fi and power** - You'll see a **"Syncing with iCloud"** status in Messages.app #### 5. Sync contacts for name resolution imessage-mcp resolves phone numbers to names usin … ## Source & license This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code. - **Author:** [anipotts](https://github.com/anipotts) - **Source:** [anipotts/imessage-mcp](https://github.com/anipotts/imessage-mcp) - **License:** MIT - **Homepage:** https://npmjs.com/package/imessage-mcp Install and usage instructions live in the source repository linked above. ## Pricing - **Free** — Free ## Security capabilities Automated source analysis of v0.1.0 — what this tool can access: - **Network access:** no - **Filesystem access:** no - **Shell / process execution:** no - **Environment & secrets:** no - **Dynamic code execution:** no *"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.* ## Versions - **0.1.0** — security scan: passed — Imported from the upstream source. ## Links - Listing page: https://agentstack.voostack.com/l/mcp-anipotts-imessage-mcp - Seller: https://agentstack.voostack.com/s/anipotts - Browse the marketplace: https://agentstack.voostack.com/browse --- Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.