sync

name	sync
description	Sync your iMessage history — builds the dataset on first run, updates incrementally after that. Use this to make sure your data is current before analysing.

Sync iMessage History

Build or update your message dataset so it's ready to query.

When to Use

• "Sync my messages"
• "Update my message history"
• "Make sure my messages are up to date"
• "Refresh my data"
• Any time status shows stale or missing data

Steps

1 — Check current state

status()

Report what you find:

• No dataset → "No dataset found, building for the first time…"
• Dataset exists, last sync < 1 hour ago → "Already up to date (last sync: X). Nothing to do."
• Dataset exists, last sync > 1 hour ago → "Updating since last sync at X…"

2 — Sync if needed

sync()

This is safe to call at any time — it does nothing if already current, and only processes new messages if stale.

3 — Confirm

Call status() again and report the result:

• Total messages indexed
• Last sync timestamp
• Dataset size

If sync fails with a permissions error

The MCP server doesn't have access to ~/Library/Messages/chat.db. This requires Full Disk Access for the app running the MCP server (Claude Desktop, Claude Code, or your terminal).

Guide the user:

To fix this, grant Full Disk Access to the app you're using: System Settings → Privacy & Security → Full Disk Access Add Claude Desktop, Claude Code, or your terminal application, then try again.

Alternatively, the user can run imessage-analysis sync once from a terminal that already has Full Disk Access — after that, the dataset exists and queries will work without special permissions.