Multimodal iMessage MCP

The most complete iMessage MCP server for Claude. Read full conversations, search messages, view image attachments, send messages, look up contacts, and react to messages -- all from Claude Desktop or Claude Code.

Why This Exists

Every other iMessage MCP tool queries the text column in Apple's chat.db. The problem? On modern macOS (14+), 93% of messages are stored in attributedBody instead of text. Those tools silently return empty or incomplete conversations.

This server reverse-engineers Apple's NSAttributedString binary format to extract the actual message content, giving you access to your complete message history.

Related MCP server: jons-mcp-imessage

Features

Multimodal: Claude Can See Your Photos

When you use get_attachment, images are returned as base64 content blocks that Claude can actually look at. HEIC photos (iPhone default) are automatically converted to JPEG. This means Claude can:

• Describe what's in a photo someone sent you

• Read text/screenshots from images

• Analyze visual content in your conversations

Requirements

• macOS (this reads the local iMessage database)

• Node.js >= 18

• Full Disk Access granted to your terminal app (System Settings > Privacy & Security > Full Disk Access). This covers both the iMessage database and the AddressBook database used for contact name resolution — no need to have the Contacts app running.

Installation

git clone https://github.com/tszaks/imessage-mcp.git
cd imessage-mcp
npm install

Configuration

Claude Desktop

Add to your ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "imessage": {
      "command": "/opt/homebrew/bin/node",
      "args": ["/path/to/imessage-mcp/index.js"]
    }
  }
}

Important: Use the full path to your Node.js binary (e.g., /opt/homebrew/bin/node), not just node. macOS desktop apps don't inherit your shell's PATH, and using a bare node command often resolves to an older system Node that causes native module crashes.

Claude Code

Add to your .mcp.json:

{
  "mcpServers": {
    "imessage": {
      "command": "node",
      "args": ["/path/to/imessage-mcp/index.js"]
    }
  }
}

In Claude Code, node typically resolves correctly since it inherits your shell environment.

Usage Examples

"Show me my recent messages" -- reads your latest conversations

"What did Mom text me today?" -- resolves "Mom" to a phone number via your AddressBook, pulls the conversation

"Search my messages for 'flight confirmation'" -- full-text search across all messages

"Find outreach prospects from the last 7 days who replied and need follow-up" -- returns structured outreach candidates with risk labels

"Preview this batch of 10 follow-up texts" -- returns exact recipients, messages, warnings, and an approval token before anything sends

"Show recent delivery failures" -- reports outgoing messages that Messages marked failed or pending, including whether a later SMS/RCS send recovered the thread

"Show me the photo from message 538516" -- returns the actual image for Claude to view and describe

"Send 'Running 10 min late' to +1234567890" -- sends an iMessage (requires confirmation)

Release Flags

Release flags are opt-in through the MCP server environment:

{
  "mcpServers": {
    "imessage": {
      "command": "node",
      "args": ["/path/to/imessage-mcp/index.js"],
      "env": {
        "IMESSAGE_MCP_RELEASES": "auto_sms_fallback,cleanup_failed_imessage_after_sms_fallback,message_mutation_tools,experimental_message_ui_actions,read_receipts"
      }
    }
  }
}

Mutation Tools

delete_messages accepts exact message ROWIDs:

{ "message_ids": ["538516", "538517"] }

It does not require confirmation. It reports deleted IDs, missing IDs, backup location, and any remaining rows found during verification.

delete_threads is a two-step exact-batch flow:

{ "chat_ids": [101, 102] }

The preview returns one approval_token for that ordered list and the thread metadata shown in the preview. To delete, send the same ordered chat_ids, confirm: true, and that token:

{ "chat_ids": [101, 102], "confirm": true, "approval_token": "..." }

Changing the order, list, or token fails the request.

edit_message and undo_send_message are experimental because Messages does not expose first-class AppleScript commands for those actions. They open the conversation, find the visible outgoing bubble by text snippet, use the contextual menu, then verify the result. They are intended to affect actual Messages behavior, not fake local-only DB edits.

Optional tuning:

IMESSAGE_MCP_SEND_VERIFY_DELAY_MS=2500

This controls how long the MCP waits before checking the local Messages database for the new outgoing row.

How It Works

The attributedBody Fix

Apple's iMessage database (~/Library/Messages/chat.db) has two columns for message content:

• text -- the legacy plain text column (used by older macOS versions)

• attributedBody -- a serialized NSAttributedString blob (used by macOS 14+)

On modern macOS, Apple gradually migrated message storage to attributedBody to support rich text, mentions, and formatting. The text column is increasingly just a legacy fallback that's often NULL.

This server detects messages with NULL text and extracts the content from attributedBody by parsing the binary NSTypedStream format:

1. Finds the NSString marker in the binary blob

2. Reads past the type header bytes (01 94 84 01 2b)

3. Decodes the length prefix (single-byte for short messages, multi-byte for longer ones)

4. Extracts the UTF-8 text payload

Attachment Handling

iMessage attachments are stored in ~/Library/Messages/Attachments/ with paths tracked in the attachment table. The get_attachment tool:

1. Queries the attachment metadata for a given message ID

2. Resolves the ~/Library/Messages/... path to an absolute path

3. For JPEG/PNG/GIF/WebP: reads the file and returns base64 image content

4. For HEIC (iPhone default): converts to JPEG using macOS sips before returning

5. For other files: returns metadata and the file path

Troubleshooting

"Failed to open iMessage database" Grant Full Disk Access to your terminal app: System Settings > Privacy & Security > Full Disk Access.

Contact lookup returns no results Contact resolution reads the macOS AddressBook SQLite databases directly (no Contacts app needed). Make sure Full Disk Access is granted. If a contact was just added, restart the MCP server to refresh the cache.

Native module crash / "NODE_MODULE_VERSION mismatch" Rebuild native dependencies: npm rebuild. This happens when your Node.js version changes. Also make sure your Claude Desktop config uses the full path to node (see Configuration above).

Missing messages from a conversation This is exactly the bug this server fixes. Make sure you're running the latest version which includes the attributedBody extraction.

License

MIT

Quickstart TL;DR

npm install
node index.js

Then add the server to your MCP client config and grant Full Disk Access to your terminal app.

How It Works (TL;DR)

• Reads macOS iMessage SQLite database

• Decodes modern attributedBody payloads for complete message text

• Exposes conversation/search/attachment tools via MCP

• Uses AppleScript for message send/reaction actions with explicit confirmations

LLM Quick Copy

Use the copy button on this code block in GitHub.

Repo: imessage-mcp
Goal: Full iMessage MCP including attachments and send/reaction actions.
Setup:
1) npm install
2) Grant Full Disk Access to terminal app
3) Add MCP config entry for index.js
Use:
- read_recent_messages, search_messages, get_conversation
- list_chats_structured, get_conversation_by_chat_id, find_outreach_followups
- get_attachment for image/file analysis
- send_message/send_message_batch/react_to_message with explicit confirm flag
How it works:
- SQLite + attributedBody decoding + AppleScript actions wrapped as MCP tools