iMessage MCP

This project exposes a read-only MCP server for the local macOS Messages database.

What it can do

• List recent chats
• Read messages from a chat
• Read messages by local date across all chats
• Search message text and subjects
• List attachments and local attachment paths
• Read text-like attachment contents
• Return attachments alongside messages
• Return server/database metadata

What it cannot do

• Send messages
• Edit messages
• Delete messages
• Mark chats or messages as read/unread
• Modify attachment files

The SQLite connection is opened in readonly mode, and the server only exposes query tools.

Attachment support

Use list_attachments to find attachments by chat or message. Use read_attachment with an attachment_id to read text-like files such as .txt, .md, .csv, .json, .html, .rtf, .doc, and .docx.

For PDFs and images, read_attachment also tries macOS Spotlight text metadata. If no text is available, binary files return metadata plus resolved_path. Import that path into AnythingLLM or use AnythingLLM's OCR/PDF pipeline to extract content.

get_messages returns attachment metadata under each message by default. Pass include_attachment_content: true to also extract readable attachment text inline with the message result.

Use get_messages_by_date for prompts such as "what messages did I send today?" Set direction to sent, received, or all. It returns message text and, when available, extracted attachment text inline.

Attachment text cache

Successful attachment text extraction is cached under cache/attachments. The cache key includes the attachment ID, local file path, file size, modified time, and max_bytes, so changed files are reprocessed automatically.

read_attachment uses the cache by default. Set use_cache: false only when you intentionally want to force OCR/PDF extraction again.

Run it

npm start

If your MCP client cannot find sqlite3, set:

export SQLITE3_PATH=/Users/lilty/miniconda3/bin/sqlite3

If your Messages database is in a different location, set:

export IMESSAGE_DB_PATH="$HOME/Library/Messages/chat.db"

MCP client config

Use this in your MCP client configuration:

{
  "mcpServers": {
    "imessage": {
      "command": "node",
      "args": ["/Users/lilty/Documents/Codex/2026-05-29/imessage-mcp/src/server.js"],
      "env": {
        "SQLITE3_PATH": "/Users/lilty/miniconda3/bin/sqlite3"
      }
    }
  }
}

Notes

• On macOS, you may need to grant Full Disk Access to the app that launches the MCP server.
• The Messages database is read directly from ~/Library/Messages/chat.db.