imessage-mcp

26 tools for locally exploring your iMessage history with AI.

if this helped you, star it. it helps others find it.

AnMCP serverthat gives AI assistantsread-onlyaccess 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.

Smithery:One-click install via the Smithery registry — search forimessage-mcp.

# Claude Code (one command) claude mcp add imessage -- npx -y imessage-mcp

# Claude Desktop — add to ~/Library/Application Support/Claude/claude_desktop_config.json

{ "mcpServers": { "imessage": { "command": "npx", "args": ["-y", "imessage-mcp"] } } }

SeeSetupfor Cursor, Windsurf, VS Code, Codex CLI, Cline, JetBrains, and Zed.
- macOS(iMessage is macOS-only)
- Node.js 18+(node --version)
- Database accessfor your host application — macOS protectschat.dbwith its Application Data permission. Grant access in:System Settings > Privacy & Security > Full Disk Accessand 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.
- Messages in iCloudenabled on your Mac (if you use multiple devices) — seeiCloud Sync & Multiple Devices

chat.db --> [imessage-mcp] --> stdio/http --> [Your MCP Client] --> AI Provider ^ ^ Your Mac only Already authorized by you

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

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

26 tools across 10 categories. All read-only. All annotated withreadOnlyHint: true.

Add to~/Library/Application Support/Claude/claude_desktop_config.json:

{ "mcpServers": { "imessage": { "command": "npx", "args": ["-y", "imessage-mcp"] } } }

claude mcp add imessage -- npx -y imessage-mcp

Or add to.mcp.jsonin your project root:

{ "mcpServers": { "imessage": { "command": "npx", "args": ["-y", "imessage-mcp"] } } }

codex --mcp-config '{"imessage":{"command":"npx","args":["-y","imessage-mcp"]}}'

{ "mcpServers": { "imessage": { "command": "npx", "args": ["-y", "imessage-mcp"] } } }

{ "mcpServers": { "imessage": { "command": "npx", "args": ["-y", "imessage-mcp"] } } }

Add to~/.codeium/windsurf/mcp_config.json:

{ "mcpServers": { "imessage": { "command": "npx", "args": ["-y", "imessage-mcp"] } } }

Add to.vscode/mcp.jsonin your project root:

{ "servers": { "imessage": { "command": "npx", "args": ["-y", "imessage-mcp"] } } }

{ "servers": { "imessage": { "type": "http", "url": "http://localhost:3000/mcp" } } }

Add via the Cline MCP settings UI, or editcline_mcp_settings.json:

{ "mcpServers": { "imessage": { "command": "npx", "args": ["-y", "imessage-mcp"] } } }

Settings > Tools > AI Assistant > MCP Servers > Add:

- Name:imessage
- Command:npx
- Args:-y imessage-mcp

{ "context_servers": { "imessage": { "command": { "path": "npx", "args": ["-y", "imessage-mcp"] } } } }

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--jsonfor machine-readable output:

# 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

By default, imessage-mcp usesstdiotransport — 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.

npx imessage-mcp --transport http --port 3000

Starts a Streamable HTTP server onhttp://127.0.0.1:3000/mcp. SupportsPOST,GET, andDELETEon/mcpwith session management viamcp-session-idheaders. This is the MCP 2025-03-26 standard.

npx imessage-mcp --transport sse --port 3000

Starts a legacy SSE server:GET /sseto establish the stream,POST /messages?sessionId=<id>for JSON-RPC requests. Use this only if your client does not support Streamable HTTP.

Run imessage-mcp as an HTTP server in Docker. Copy yourchat.dbto a volume mount:

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.0on port 3000 by default. Connect any MCP client tohttp://localhost:3000/mcp.

To secure the HTTP endpoint with authentication:

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 theAuthorization: Bearer your-secret-tokenheader.

Prevent message bodies from being sent to the AI. Only metadata (counts, dates, contact names) is returned. No actual message text.

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

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), passinclude_all: trueto any filtered tool.

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, seeiCloud Sync & Multiple Devices.

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

imessage-mcp reads your Mac's local database (~/Library/Messages/chat.db). This database only contains messages that have beensynced 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 inchat.db.

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" enabledon your Mac, the Mac'schat.dbonly contains messages sent and received while Messages.app was actively running on that Mac.
- OpenMessages.appon your Mac
- Go toSettings(Cmd+,) >iMessagetab
- Check"Enable Messages in iCloud"
- Keep Messages.app open — sync begins automatically
- OpenSettings> tap yourname(Apple ID) >iCloud>Messages
- Toggle"Use on this iPhone"ON

All devices must be signed into thesame Apple ID. Check: Mac (System Settings > Apple ID), iPhone (Settings > tap your name).

Initial sync can takehours or even daysfor large message histories. During sync:

- Messages.app must remainopenon your Mac
- Your Mac should be connected toWi-Fi and power
- You'll see a"Syncing with iCloud"status in Messages.app

imessage-mcp resolves phone numbers to names using your Mac's AddressBook. If contacts only exist on your iPhone:
- OpenSystem Settings>Apple ID>iCloud
- FindContactsand toggle itON
- Wait for contacts to sync (usually under a minute)

Look for theMessagesline — it shows how many messages are indexed locally. If this number seems low, iCloud sync is likely still in progress. Rundoctoragain later to confirm the count has stabilized.

Tip:On your iPhone, go toSettings > General > iPhone Storage > Messagesto see your total message history size. Compare with whatdoctorreports on your Mac.

Messages on iPhone don't appear on Mac:"Messages in iCloud" must be enabled onbothdevices. Ensure both use the same Apple ID. Keep Messages.app open on your Mac. Runnpx imessage-mcp doctorperiodically to check if the count is growing.

Brand-new Mac shows no history:Expected — enable "Messages in iCloud," connect to Wi-Fi and power, keep Messages.app open. For large histories (100K+ messages), initial sync may take 1–2 days.