iMessage MCP

Install

Config snippet generator goes here (5 client tabs)

README

# imessage-mcp

[![npm version](https://img.shields.io/npm/v/imessage-mcp?style=flat-square)](https://www.npmjs.com/package/imessage-mcp)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg?style=flat-square)](https://opensource.org/licenses/MIT)
[![TypeScript](https://img.shields.io/badge/TypeScript-5.x-blue?style=flat-square&logo=typescript&logoColor=white)](https://www.typescriptlang.org/)
[![MCP](https://img.shields.io/badge/MCP-Compatible-8A2BE2?style=flat-square)](https://modelcontextprotocol.io)
[![CI](https://github.com/anipotts/imessage-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/anipotts/imessage-mcp/actions/workflows/ci.yml)
[![Node](https://img.shields.io/badge/Node.js-18%2B-339933?style=flat-square&logo=node.js&logoColor=white)](https://nodejs.org)

**26 tools for locally exploring your iMessage history with AI.**

<img src="https://raw.githubusercontent.com/anipotts/imessage-mcp/main/assets/demo-dark.gif" alt="imessage-mcp demo" width="100%">

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

<details>
<summary><strong>More examples</strong></summary>

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

</details>

<picture>
  <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/anipotts/imessage-mcp/main/assets/wrapped-dark.png">
  <source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/anipotts/imessage-mcp/main/assets/wrapped-light.png">
  <img src="https://raw.githubusercontent.com/anipotts/imessage-mcp/main/assets/wrapped-dark.png" alt="iMessage Wrapped — year-in-review summary" width="100%">
</picture>

## 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_