imessage

imessage-mcp

26 tools for locally exploring your iMessage history with AI.

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

An MCP server that gives AI assistants read-only access 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.

Read-only access to 2 local files (chat.db + AddressBook). Zero network requests. Nothing is written, uploaded, or shared. All 26 tools are annotated readOnlyHint: true — your MCP client can auto-approve every call without prompts.

Install

npm install -g imessage-mcp

Or run without installing:

npx imessage-mcp doctor

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

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.

Claude Code Plugin

For slash commands and agents:

claude plugin add anipotts/imessage-mcp

Prerequisites

1. macOS (iMessage is macOS-only)
2. Node.js 18+ (node --version)
3. Database access for your host application — macOS protects chat.db with its Application Data permission. Grant access in: System Settings > Privacy & Security > Full Disk Access and 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.
4. Messages in iCloud enabled on your Mac (if you use multiple devices) — see iCloud Sync & Multiple Devices

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.

Path	Access	Purpose
~/Library/Messages/chat.db	Read-only	Your iMessage database
~/Library/Application Support/AddressBook/	Read-only	Contact name resolution

No other files are accessed. No external APIs are called.

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

What Can You Ask?

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

More examples

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

Tools

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