imessage-mcp
This server lets Claude locally read and search your macOS Messages history, track new messages, and optionally send texts via Messages.app.
List chats: browse recent iMessage/SMS chats, with optional substring filtering by chat/contact name or identifier.
Read threads: fetch messages from a specific chat in date order, with sender names, attachments, and tapback reactions; supports date filters and limits.
Search messages: case-insensitive substring search across decoded message bodies, optionally scoped to one chat and/or a start date.
Track what’s new: return all messages since the last cursor, grouped by chat, with a 24-hour default on first use.
Send messages: optionally send through Messages.app only when
IMESSAGE_SEND=1is set; disabled by default.Privacy: everything runs locally against read-only SQLite databases, with no network calls.
Provides tools to read macOS Messages history, list chats, read threads with sender names and reactions, search message bodies, see new messages across chats, and optionally send messages through Messages.app.
Click on "Deploy 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-mcp search my iMessage history for mentions of 'apartment'"
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
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.
Related MCP server: iMessage MCP Server
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.dbwill 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 syncRegister with Claude Code
claude mcp add --scope user imessage -- uv run --directory /Users/clint/Projects/imessage-mcp python -m imessage_mcp.serverThat 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 pytestThe 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 theattributedBodyblob that Messages uses instead of plaintextfor most rows.imessage_mcp/db.py: all the read only SQL againstchat.dband Contacts.imessage_mcp/server.py: the FastMCP server and tool definitions.tests/: pytest tests against the live database.
Running as a launchd service (survives Claude Code updates)
macOS grants Full Disk Access to the process that launchd started. When Claude Code spawns this server over stdio, that process is Claude Code's own daemon, whose binary path changes on every self-update, so the grant dies each time (seen 2026-11-03 and 2026-11-04). The fix is to run the server as its own launchd agent from a binary path that never changes and talk to it over HTTP.
./install-service.shWhat it does:
copies the
uvbinary to~/.local/share/imessage-mcp/imessage-mcp(a fixed path; never replace that file or the grant breaks)installs
~/Library/LaunchAgents/com.clint.imessage-mcp.plist, which runsimessage-mcp run --directory <project> python -m imessage_mcp.server --httpon127.0.0.1:8471, KeepAlive, log at~/Library/Logs/imessage-mcp.logrewrites
mcpServers.imessagein~/.claude.jsonto{"type": "http", "url": "http://127.0.0.1:8471/mcp"}(backup kept beside it)
Then, once, by hand: System Settings > Privacy & Security > Full Disk Access,
add ~/.local/share/imessage-mcp/imessage-mcp and switch it on, and restart
the agent:
launchctl kickstart -k gui/$(id -u)/com.clint.imessage-mcpUseful commands:
launchctl print gui/$(id -u)/com.clint.imessage-mcp | grep -E "state|pid"
tail -f ~/Library/Logs/imessage-mcp.logThe stdio mode still works (python -m imessage_mcp.server with no flag) for
other MCP clients. --http or IMESSAGE_MCP_HTTP=1 selects HTTP;
IMESSAGE_MCP_HOST and IMESSAGE_MCP_PORT override the bind address.
Available Tools
5 toolslist_chatsA
List recent iMessage/SMS chats, optionally filtered by a case insensitive substring match against the chat name, contact names, or chat identifier. Returns one line per chat with ROWID, name, last message time, and message count.
Inputs: limit, query. Returns: result
read_threadA
Read messages from one chat, in date order.
chat accepts a chat ROWID, a chat guid/chat_identifier, or a case
insensitive substring of a contact/display name. If the name is
ambiguous, this returns a list of candidate chats instead of messages.
since is an optional "YYYY-MM-DD" or "YYYY-MM-DD HH:MM" local time
filter. limit caps how many of the most recent matching messages come
back (still returned oldest first).
Inputs: chat (required), limit, since. Returns: result
searchA
Search decoded message bodies for a substring (case insensitive).
Optionally restrict to one chat (same matching rules as read_thread) and
to messages on or after since ("YYYY-MM-DD" or "YYYY-MM-DD HH:MM").
Inputs: text (required), chat, limit, since. Returns: result
sendA
Send a message through Messages.app.
Disabled by default. Set the environment variable IMESSAGE_SEND=1 on
this server process to enable it. chat accepts the same matching rules
as read_thread. Always show the exact text to the user and get a yes
before calling this.
Inputs: chat (required), text (required). Returns: result
whats_newA
Return every message across all chats since the last time this tool advanced its cursor, grouped by chat, oldest first within each chat.
On the very first call (no cursor yet) it returns the last 24 hours.
The cursor lives at ~/.imessage-mcp/cursor.json. When mark_seen is
true (the default), the cursor advances to the newest message ROWID seen
so the next call only returns messages after this one.
Inputs: mark_seen. Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 5 tools
Each tool targets a distinct action: listing chats, reading a thread, searching messages, incremental polling, and sending. Even though read_thread and search both return messages, their purposes are clearly separated and easy to tell apart.
list_chats and read_thread follow a verb_noun pattern, while search and send are bare verbs and whats_new is a phrase. All names use lower_snake_case and are readable, but the naming is not fully uniform.
Five tools is a well-scoped set for an iMessage bridge. It covers the main interactions without unnecessary redundancy or surface-area bloat.
The tool set covers the core messaging workflow: enumerate chats, read conversations, search content, poll for new messages, and send replies. There are no obvious dead ends or missing operations for the stated domain.
Maintenance
Related MCP Connectors
iMessage for AI agents, from your iPhone. No Mac needed, and you choose which chats they read.
Your Telegram, WhatsApp, Instagram, mail and calendar in Claude or ChatGPT. Never sends messages.
Connect any IMAP/SMTP mailbox to Claude & ChatGPT: search, read, sort, draft. Sends only with OK.
MCP connector for iMessage & Contacts via a local Mac agent + Vercel relay
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceEnables Claude to send and read iMessages on macOS, with smart contact lookup, message history retrieval, and cross-conversation search using natural language commands.6MIT
- AlicenseNot gradedqualityDmaintenanceEnables Claude to read and search through iMessage, SMS, and RCS conversations, including mixed-protocol group chats with Android users. It decodes binary message data from the macOS Messages database to provide a comprehensive view of message history.8 npmMIT
- AlicenseAqualityDmaintenanceConnects Claude Desktop to iMessage on macOS, enabling reading conversations, searching messages, sending texts, and managing attachments.714 npmMIT
- AlicenseNot gradedqualityDmaintenanceEnables Claude to send and receive iMessage/SMS messages through macOS, with support for attachments, chat history, and real-time message monitoring.MIT