imessage-mcp

A local MCP (Model Context Protocol) server that lets Claude Code read your macOS Messages history directly, so you stop copy-pasting text threads into chat by hand.

It reads ~/Library/Messages/chat.db and your local Contacts database directly with Python's stdlib sqlite3. There are no native dependencies and nothing leaves your Mac: every tool is a local, read-only SQL query plus a small typedstream decoder for the message bodies that Messages stores as binary blobs.

What it gives Claude

• list_chats(query, limit): recent chats, with names resolved from Contacts.
• read_thread(chat, since, limit): a thread in order, with sender names, attachment paths, and tapback reactions folded into the message they landed on.
• search(text, chat, since, limit): full text search over decoded message bodies.
• whats_new(mark_seen): everything new across every chat since the last call, using a small cursor file at ~/.imessage-mcp/cursor.json.
• send(chat, text): sends a message through Messages.app. Disabled unless you explicitly turn it on, see "Sending" below.

Requirements

• macOS with Messages.app signed in and syncing.
• Full Disk Access granted to whatever process runs this server (your terminal, or Claude Code itself, depending on how you launch it). Without it, ~/Library/Messages/chat.db will fail to open even in read-only mode. Grant it under System Settings, Privacy and Security, Full Disk Access.
• Python 3.12 or newer, managed with uv.

Install

cd /Users/clint/Projects/imessage-mcp
uv sync

Register with Claude Code

claude mcp add --scope user imessage -- uv run --directory /Users/clint/Projects/imessage-mcp python -m imessage_mcp.server

That registers the server once, for every project, over stdio.

Sending is off by default

send(chat, text) only works when the server process has the environment variable IMESSAGE_SEND=1 set. Without it, the tool returns a plain message saying sending is disabled, and does nothing else.

When enabled, sending goes through osascript and Messages.app:

• a one on one chat sends with send text to buddy handle of (service 1 whose service type is iMessage).
• a group chat sends with send text to chat id "<guid>".

The first send will prompt macOS for Automation permission for whatever process is driving Messages.app. Treat this as a real send: nothing here double checks with you before the message goes out, so only turn IMESSAGE_SEND on in a session where you are prepared to review the exact text before asking the tool to send it.

Privacy

Everything runs locally. The server opens chat.db and your Contacts database read only (sqlite3 URI mode=ro), decodes text and attachment paths in process, and returns plain text to Claude. Nothing is uploaded anywhere, and no network calls happen anywhere in this codebase.

Tests

uv run pytest

The tests read your live chat.db and Contacts database and skip themselves cleanly if either is unreadable (for example, no Full Disk Access, or run on a machine with no Messages history).

Layout

• imessage_mcp/typedstream.py: decodes the attributedBody blob that Messages uses instead of plain text for most rows.
• imessage_mcp/db.py: all the read only SQL against chat.db and Contacts.
• imessage_mcp/server.py: the FastMCP server and tool definitions.
• tests/: pytest tests against the live database.