Imessage MCP Server

iMessage MCP server — 26 tools for searching, analyzing, and exploring your entire iMessage history on macOS

Local serverstdioGo

What is the Imessage MCP Server?

iMessage MCP server — 26 tools for searching, analyzing, and exploring your entire iMessage history on macOS

What the server does

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.

Credentials and setup notes

  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

Recorded tools

  • search_messages — Full-text search with filters: query, contact, date range, direction, group chat, attachments
  • yearly_wrapped — Spotify Wrapped for iMessage — full year summary
  • who_initiates — Who starts conversations? Initiation ratio per contact
  • streaks — Consecutive-day messaging streaks
  • get_reactions — Tapback distribution, top reactors, most-reacted messages
  • on_this_day — Messages from this date in past years
  • get_conversation — Conversation thread with cursor-based pagination
  • list_contacts — All contacts with message counts and date ranges
  • get_contact — Deep contact info with stats and yearly breakdown
  • resolve_contact — Fuzzy-match a name, phone number, or email to a contact
  • message_stats — Aggregate stats with time-series grouping
  • contact_stats — Per-contact volumes, trends, and hourly patterns
  • temporal_heatmap — 7x24 activity heatmap (day-of-week by hour)
  • first_last_message — First and last message ever exchanged with a contact

More MCP options

Compare MCP servers by category, or browse hosted MCP servers if you prefer an endpoint over a local process.

Maintainer setup documentation.

Recorded tools

Check the linked publisher documentation and your connected client's tool list. Names and availability can vary with the server version and account permissions.

ToolWhat it does
search_messagesSearch by substring, exact text, token, or phrase. Message text by default; conversation names and attachment filenames are opt-in. Filter by service, sent or r
get_conversationRead a conversation by chat_id or by a contact or group name, with edits, reactions, receipts, replies, group events, and attachments. The cursor pages to older
list_conversationsFind conversations by contact, service, kind, reply state, or date, each with its latest message, newest first or by who you text most
get_attachmentShow one attachment from get_conversation: images as a JPEG with location and camera metadata removed, text files as text. Needs the full privacy mode
sync_messagesPull every change since a cursor: new, edited, unsent, and deleted messages, reactions, and receipts
analyze_communicationMessage counts by hour and weekday, response times, streaks, and who starts conversations
resolve_contactMatch a name, phone number, or email to a contact in your Mac's Address Book, and report ambiguity rather than guess
server_statusVersion, update availability, privacy mode, index state, schema support, and Contacts access

How to install the Imessage MCP Server

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

From the project documentation. Replace placeholders and example paths before connecting.

Configuration

  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

Example prompts to try

  • “Use Imessage MCP to search messages.”
  • “Use Imessage MCP to yearly wrapped.”
  • “Use Imessage MCP to who initiates.”

Frequently asked questions

iMessage MCP server — 26 tools for searching, analyzing, and exploring your entire iMessage history on macOS Confirm the tools offered by your installed version in the connected client. Tool availability and permissions depend on the server and account configuration.