Allows for the exploration of local Apple messaging data, including iMessage history, contact information from the AddressBook, and metadata like message effects and tapback reactions.
Provides read-only access to iMessage history for full-text search, conversation analysis, reaction tracking, and detailed messaging statistics such as streaks and response patterns.
Integrates with the local macOS environment to access the iMessage database (chat.db) and AddressBook contacts to provide insights into messaging history and trends.
Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@imessage-mcpSearch my messages with Sarah for the address she sent last week"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
imessage-mcp
25 tools for exploring your iMessage history on macOS.
Read-only access to your Mac's iMessage database — search messages, analyze conversations, explore reactions, read receipts, reply threads, edited messages, effects, streaks, conversation patterns, and more.
What is MCP?
Model Context Protocol (MCP) is an open standard that lets AI assistants like Claude connect to external data sources. imessage-mcp gives Claude (or any MCP client) read-only access to your local iMessage database so you can ask questions about your messaging history in natural language.
Setup
1. Grant Full Disk Access to your terminal app:
System Settings → Privacy & Security → Full Disk Access → enable your terminal app (Terminal, iTerm2, Warp, etc.)
2. Run diagnostics:
3. Add to Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json):
4. Restart Claude Desktop. Ask it "search my messages for coffee" — done.
Tools
Tool | Category | What it does |
| Messages | Full-text search with filters (query, contact, date, direction, group, attachments) |
| Messages | Conversation thread with cursor-based pagination |
| Contacts | All contacts with message counts and date ranges |
| Contacts | Deep contact info: stats, yearly breakdown |
| Contacts | Fuzzy-match name/phone/email to contact |
| Analytics | Aggregate stats with time-series grouping |
| Analytics | Per-contact volumes, trends, hourly patterns |
| Analytics | 7×24 activity heatmap (day-of-week × hour) |
| Memories | Messages from this date in past years |
| Memories | First and last message ever exchanged with a contact |
| Patterns | Who starts conversations? Initiation ratio per contact |
| Patterns | Consecutive-day messaging streaks |
| Patterns | Detect double-texting and unanswered message patterns |
| Patterns | Find the longest silences in a conversation |
| Patterns | Contacts you've lost touch with |
| Wrapped | Spotify Wrapped for iMessage — full year summary |
| Groups | Group chats with member counts and activity |
| Groups | Per-member stats, monthly activity timeline |
| Attachments | Query by contact, MIME type, date range |
| Reactions | Tapback distribution, top reactors, most-reacted messages |
| Receipts | Read/delivery latency, unread patterns |
| Threads | Reconstruct reply thread trees |
| Edits | Edited and unsent messages with timing |
| Effects | Slam, loud, confetti, fireworks analytics |
| System | Full tool guide and examples |
Example Queries
Once connected, try asking Claude things like:
"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?"
CLI Commands
imessage-mcp
Start the MCP server (stdio transport). This is what Claude Desktop calls automatically.
imessage-mcp doctor
Run setup diagnostics. Checks macOS, Node version, chat.db access, Full Disk Access, AddressBook, and message count.
Pass --json for machine-readable output:
imessage-mcp dump
Export messages to JSON. Pipe to a file or process with jq.
Privacy
imessage-mcp reads your local iMessage database in read-only mode. No data leaves your machine — all queries run locally against ~/Library/Messages/chat.db. Nothing is written, modified, uploaded, or shared. Contact names are resolved from your macOS AddressBook locally. No external APIs are called.
Troubleshooting
"Cannot read chat.db" / SQLITE_CANTOPEN
Grant Full Disk Access to your terminal: System Settings → Privacy & Security → Full Disk Access → enable your terminal app. Then restart your terminal.
"No messages found"
Make sure Messages.app has been used on this Mac and has synced your messages. Run npx imessage-mcp doctor to verify.
Messages show phone numbers instead of names
Contact resolution uses your macOS AddressBook. If contacts aren't synced to your Mac (e.g. only on your phone), names won't resolve. Sync contacts via iCloud or add them in the Contacts app.
Claude Desktop doesn't show the tools
Make sure the config file is at
~/Library/Application Support/Claude/claude_desktop_config.jsonRestart Claude Desktop completely (Cmd+Q, then reopen)
Run
npx imessage-mcp doctorto verify the server works
How It Works
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 — no configuration needed.
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 — no messages left behind.
All 25 tools are annotated with readOnlyHint: true so MCP clients can auto-approve them without prompting.
Configuration
Env var | Default | Description |
|
| Path to iMessage database |
Requirements
macOS (iMessage is macOS-only)
Node.js 18+
Full Disk Access for your terminal app
License
MIT