Submit
joshkaplan-dev

Read-only iMessage MCP server

Community joshkaplan-dev
Updated

Read-only macOS iMessage MCP server

Read-only iMessage MCP server

Gives an assistant read-only access to your macOS Messages so it can help youread, search, and analyze texts. It cannot send, edit, or delete anything —every database connection is opened with SQLite mode=ro. You send replies yourself.

What it reads

  • ~/Library/Messages/chat.db — your iMessage/SMS history (read-only)
  • ~/Library/Application Support/AddressBook/.../AddressBook-v22.abcddb — to turnphone numbers/emails into contact names (read-only, best effort)

It never writes to, copies, or transmits these anywhere — it just answers queriesfrom whichever Claude client is connected.

Tools

Tool What it does
list_conversations Most recently active threads + last-message preview
list_unreplied Threads where the other person texted last (awaiting your reply)
get_conversation Recent message history with a person or group (fuzzy name/phone/email match)
search_messages Full-text search across messages, optionally scoped to one contact
get_recent_messages Inbox-style view of recent messages across all threads (optional hours window)

Requirements

  • uv installed (handles the Python deps automatically).
  • Full Disk Access for whatever app runs the server, because chat.db is protected:
    • Claude Code (CLI): the terminal app you launch claude from (Terminal, iTerm, etc.).
    • Claude Desktop: the Claude.app itself.Grant it in System Settings → Privacy & Security → Full Disk Access, then restart the app.

How it's wired up

  • Claude Code: registered at user scope (~/.claude.json).Remove with claude mcp remove imessage-readonly.
  • Claude Desktop: added under mcpServers in~/Library/Application Support/Claude/claude_desktop_config.json(a timestamped .bak of the original sits next to it). Restart the app to load it.

Notes

  • On recent macOS the message text is stored in a binary attributedBody blob ratherthan the text column; server.py decodes it (handles emoji/accents).
  • Timestamps are converted from Apple absolute time (nanoseconds since 2001-01-01).
  • Override the database path with the IMESSAGE_DB environment variable if needed.

MCP Server · Populars

MCP Server · New