imessage-mcp

25 tools for exploring your iMessage history on macOS.

An MCP server that gives AI assistants read-only access to your local iMessage database. Search messages, analyze conversations, explore reactions, read receipts, reply threads, edited messages, effects, streaks, conversation patterns, and more. Nothing leaves your machine.

Install

npm install -g imessage-mcp

Or run without installing:

npx imessage-mcp doctor

Add to your AI client

# 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"] } } }

See Setup for Cursor, Windsurf, VS Code, Codex CLI, Cline, JetBrains, and Zed.

Prerequisites

1. macOS (iMessage is macOS-only)
2. Node.js 18+ (node --version)
3. Full Disk Access for your terminal: System Settings > Privacy & Security > Full Disk Access

Tools

25 tools across 9 categories. All read-only. All annotated with readOnlyHint: true for auto-approval.

Messages

Contacts

Analytics

Memories

Patterns

Wrapped

Groups

Attachments & Media

Reactions, Receipts, Threads, Edits & Effects

System

What Can You Ask?

Once connected, ask your AI assistant anything about your messages in plain language:

• "How many messages have I sent this year?"
• "Show my conversation with Mom"
• "Who reacts to my messages the most?"
• "What time of day am I most active texting?"
• "What was the first text I ever sent my partner?"
• "What was I texting about on this day last year?"
• "Do I always text first with [name]?"
• "What's my longest texting streak?"
• "Show me messages people unsent"
• "Give me my 2024 iMessage Wrapped"
• "Who have I lost touch with?"
• "Show me the longest silence between me and [name]"
• "Do I double-text [name] a lot?"
• "What are the most popular group chats?"

Setup

Claude Desktop

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

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

Restart Claude Desktop after saving.

Claude Code

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

Or add to .mcp.json in your project root:

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

OpenAI Codex CLI

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

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

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

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

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

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

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

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

CLI Commands

imessage-mcp doctor

Run setup diagnostics. Checks macOS version, Node.js version, chat.db access, Full Disk Access, 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
  ✓ Full Disk 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

imessage-mcp dump

Export messages or contacts to JSON.

# 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

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.

The tool accesses exactly two locations on disk:

No other files are accessed. No external APIs are called. You can verify this yourself:

grep -rn "readFileSync\|openDatabase\|sqlite" src/

Why Full Disk Access?

macOS protects ~/Library/Messages/chat.db. Your terminal needs Full Disk Access to read it. This is an Apple requirement, not something imessage-mcp imposes.

How your data flows

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

imessage-mcp makes zero network requests. Your data only leaves your machine through your MCP client (Claude Desktop, Cursor, etc.), which you have already authorized separately.

Safe Mode

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.

Smart Filtering

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. These always return results for any contact you specify.

To include all contacts (including unrecognized senders), pass include_all: true to any filtered tool.

Configuration

Troubleshooting

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

How It Works

imessage-mcp reads ~/Library/Messages/chat.db using better-sqlite3 in read-only mode with query_only = ON. Contact names are resolved from your macOS AddressBook automatically.

On macOS 14 (Sonoma) and later, Apple changed how message text is stored. Some messages have NULL in the text column but contain the actual text in the attributedBody binary blob. imessage-mcp extracts text from this blob automatically so no messages are left behind.

All 25 tools are annotated with readOnlyHint: true so MCP clients can auto-approve them without user prompts.

Requirements

• macOS -- iMessage is macOS-only
• Node.js 18+
• Full Disk Access for your terminal app

License

MIT