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

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

Or add to ~/.codex/config.json:

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

Add to ~/.cursor/mcp.json:

{
  "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.json in your project root:

stdio (default):

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

HTTP transport (remote / Docker):

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

Add via the Cline MCP settings UI, or edit cline_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

Add to ~/.config/zed/settings.json:

{
  "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 --json for machine-readable output:

npx imessage-mcp doctor --json

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.

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

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

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), pass include_all: true to 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, see 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):

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

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 using your Mac's AddressBook. If contacts only exist on your iPhone:

1. Open System Settings > Apple ID > iCloud
2. Find Contacts and toggle it ON
3. Wait for contacts to sync (usually under a minute)

Verify sync is complete

npx imessage-mcp doctor

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

Tip: On your iPhone, go to Settings > General > iPhone Storage > Messages to see your total message history size. Compare with what doctor reports on your Mac.

Common sync issues

Messages on iPhone don't appear on Mac: "Messages in iCloud" must be enabled on both devices. Ensure both use the same Apple ID. Keep Messages.app open on your Mac. Run npx imessage-mcp doctor periodically 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.

History is incomplete: Sync may still be in progress. If iCloud storage is full, sync pauses (check System Settings > Apple ID > iCloud > Manage Storage). Messages sent while sync was disabled won't sync retroactively.

Group chats missing members: Group chat sync can lag behind 1:1 conversations. Ensure sync is enabled on all devices and has had time to complete. If members show as phone numbers, enable iCloud Contacts sync (step 5 above).

macOS protects chat.db with its Application Data permission. To grant access:

1. Open System Settings > Privacy & Security > Full Disk Access
2. Enable the app running the MCP server (your terminal, Claude Desktop, Cursor, etc.)
3. Restart the app after granting access

GUI apps like Claude Desktop and Cursor may already have this permission — try running npx imessage-mcp doctor first.

imessage-mcp reads only messages synced to your Mac. See iCloud Sync & Multiple Devices for full setup steps.

Quick checklist:

1. Open Messages.app > Settings > iMessage > enable "Messages in iCloud"
2. Ensure the same Apple ID is signed in on all your devices
3. Connect to Wi-Fi and power — initial sync can take hours
4. Run npx imessage-mcp doctor to check message count

Make sure Messages.app has been used on this Mac and has synced your messages. If you recently set up this Mac or just enabled "Messages in iCloud," sync may still be in progress — see iCloud Sync & Multiple Devices. Run npx imessage-mcp doctor to verify your setup and message count.

Contact resolution uses your macOS AddressBook. If contacts are only on your phone and not synced to your Mac, names will not resolve. See iCloud Sync & Multiple Devices for instructions on enabling iCloud contact sync, or add contacts manually in the Contacts app.

Your MCP client's bundled Node.js version differs from the one that compiled better-sqlite3's native module. Fix by pointing to your system Node directly:

1. Find your Node path: which node
2. Find imessage-mcp: npm root -g
3. Replace "command": "npx" with your system Node:

{
  "mcpServers": {
    "imessage": {
      "command": "/opt/homebrew/bin/node",
      "args": ["/path/to/node_modules/imessage-mcp/bin/imessage-mcp.js"]
    }
  }
}

1. Verify the config file is at ~/Library/Application Support/Claude/claude_desktop_config.json
2. Restart Claude Desktop completely (Cmd+Q, then reopen)
3. Run npx imessage-mcp doctor to confirm the server works independently