# iMessage History

This MCP server searches and reads Apple Messages history on macOS. Use it when an agent needs conversation context without sending messages.

- MCP server · `type=mcp` · Claude Code, Codex, Cursor, GitHub Copilot, Windsurf (Devin Desktop), Cline, Zed, Gemini CLI · ★ 28
- Author: anipottsbuilds
- License: MIT · policy=link-only · description only; the file stays with the author
- Source: https://github.com/anipottsbuilds/imessage-mcp
- Updated: 2026-10-23
- HTML: https://affpapa.org/en/nevibecode/mcp/anipottsbuilds-imessage-history

## What it does

iMessage History gives an MCP client local access to Apple Messages history. It can look up messages by words, exact text, or phrases, read conversation details with reactions and replies, display sent photos, and follow new activity. The server is read-only, so it cannot send a drafted reply.

It runs on a Mac without an account or a build step. The `npx` setup needs macOS 14 or later and Node.js 24.16 or later; Node 24 LTS is advised for encrypted cache support. Full Disk Access is required for the host application, and the app must be restarted after permission changes. Node 25 lacks the SQLite checkpoint APIs used for persistent search state, so searches stay in memory and are rebuilt after a restart.

## Requirements
- Needs: Node.js (commands run via npx)
- Environment variables: `IMESSAGE_PRIVACY`, `IMESSAGE_CONTACTS`, `IMESSAGE_DB`, `IMESSAGE_CACHE`, `IMESSAGE_UPDATE_CHECK` — keys and tokens: ask the human for the values, never commit them or put them in shared files.

## Install

### Claude Code (native platform)

**Platform CLI**
```bash
claude mcp add --env IMESSAGE_PRIVACY=<IMESSAGE_PRIVACY> --env IMESSAGE_CONTACTS=<IMESSAGE_CONTACTS> --env IMESSAGE_DB=<IMESSAGE_DB> --env IMESSAGE_CACHE=<IMESSAGE_CACHE> --env IMESSAGE_UPDATE_CHECK=<IMESSAGE_UPDATE_CHECK> --transport stdio anipottsbuilds-imessage-history -- npx -y imessage-mcp
```
Replace <…> with your own values

### Codex

**Platform CLI**
```bash
codex mcp add anipottsbuilds-imessage-history --env IMESSAGE_PRIVACY=<IMESSAGE_PRIVACY> --env IMESSAGE_CONTACTS=<IMESSAGE_CONTACTS> --env IMESSAGE_DB=<IMESSAGE_DB> --env IMESSAGE_CACHE=<IMESSAGE_CACHE> --env IMESSAGE_UPDATE_CHECK=<IMESSAGE_UPDATE_CHECK> -- npx -y imessage-mcp
```
Replace <…> with your own values

### Cursor

**Config file**
File `.cursor/mcp.json`:
```json
{
    "mcpServers": {
        "anipottsbuilds-imessage-history": {
            "command": "npx",
            "args": [
                "-y",
                "imessage-mcp"
            ],
            "env": {
                "IMESSAGE_PRIVACY": "<IMESSAGE_PRIVACY>",
                "IMESSAGE_CONTACTS": "<IMESSAGE_CONTACTS>",
                "IMESSAGE_DB": "<IMESSAGE_DB>",
                "IMESSAGE_CACHE": "<IMESSAGE_CACHE>",
                "IMESSAGE_UPDATE_CHECK": "<IMESSAGE_UPDATE_CHECK>"
            }
        }
    }
}
```
Replace <…> with your own values

### GitHub Copilot

**Config file**
File `.vscode/mcp.json`:
```json
{
    "servers": {
        "anipottsbuilds-imessage-history": {
            "type": "stdio",
            "command": "npx",
            "args": [
                "-y",
                "imessage-mcp"
            ],
            "env": {
                "IMESSAGE_PRIVACY": "<IMESSAGE_PRIVACY>",
                "IMESSAGE_CONTACTS": "<IMESSAGE_CONTACTS>",
                "IMESSAGE_DB": "<IMESSAGE_DB>",
                "IMESSAGE_CACHE": "<IMESSAGE_CACHE>",
                "IMESSAGE_UPDATE_CHECK": "<IMESSAGE_UPDATE_CHECK>"
            }
        }
    }
}
```
Replace <…> with your own values

### Gemini CLI

**Platform CLI**
```bash
gemini mcp add -e IMESSAGE_PRIVACY=<IMESSAGE_PRIVACY> -e IMESSAGE_CONTACTS=<IMESSAGE_CONTACTS> -e IMESSAGE_DB=<IMESSAGE_DB> -e IMESSAGE_CACHE=<IMESSAGE_CACHE> -e IMESSAGE_UPDATE_CHECK=<IMESSAGE_UPDATE_CHECK> anipottsbuilds-imessage-history npx -y imessage-mcp
```
Replace <…> with your own values

## When to use it
- find a message by a word or phrase
- read a full conversation before replying
- summarize message activity for the week
- identify contacts waiting for a reply
- check a contact’s usual response time

## Example prompts
- Search my messages for the dinner reservation and summarize the relevant conversation.
- Tell me who is waiting for my reply and what each person needs.
- Review this week’s messages and report the busiest conversations and pending replies.

## Similar
- [REA](https://affpapa.org/en/nevibecode/mcp/rea.md) — MCP server · ★ 386989
- [GitHub](https://affpapa.org/en/nevibecode/mcp/github.md) — MCP server · ★ 33918
- [Netdata](https://affpapa.org/en/nevibecode/mcp/netdata.md) — MCP server · ★ 81115
- [browser-use](https://affpapa.org/en/nevibecode/mcp/browser-use.md) — MCP server · ★ 119160
- [Codebase Memory](https://affpapa.org/en/nevibecode/mcp/codebase-memory.md) — MCP server · ★ 47392
- [mcp-server](https://affpapa.org/en/nevibecode/mcp/mcp-server.md) — MCP server · ★ 43872

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md