imessage_mcp

Local MCP server for macOS Messages + Contacts: send messages, read chat history, wait for a reply without polling manually, and look up/update Contacts.app entries.

Runs over stdio, driven directly by whatever agent/client launches it (e.g. Claude Code, Claude Desktop). Only tested on and intended for macOS.

Setup

cd imessage-mcp
python3 -m venv .venv
.venv/bin/pip install -r requirements.txt

macOS permissions

The process that actually runs this server (not your terminal, unless that's what launches it) needs, under System Settings > Privacy & Security:

• Full Disk Access — to read ~/Library/Messages/chat.db directly.

• Automation — to control Messages.app and Contacts.app via osascript.

macOS prompts for these the first time each permission is needed; if a prompt doesn't appear, add the process manually in System Settings. If you're running this via Claude Code/Desktop, that's typically the app itself (or the terminal it was launched from) that needs the grant, not the Python interpreter.

Register with Claude Code

claude mcp add imessage-mcp -- bash -c "cd /Users/john/mcp/imessage-mcp && .venv/bin/python -m imessage_mcp.server"

The cd wrapper is required: this must run as python -m imessage_mcp.server (a package, for the relative imports between modules) rather than by direct script path, and -m only finds the package if the process's working directory is the project root -- which isn't guaranteed to be true when Claude Code launches it from wherever you happen to be working.

Use -s user instead of the default local scope if you want it available across all projects, not just this directory.

Related MCP server: iMessage MCP

Tools

Known limitations

• Contacts.app duplicate cards: it's common for the same real person to have 2+ separate person records. imessage_search_contacts returns all of them; keeping a contact's info consistent may mean calling the update tools once per duplicate id.

• Contact ids can go stale: with iCloud Contacts sync on, a person's id can change shortly after it's created or edited (sync reassigns/ merges the record). If an update call errors saying the contact wasn't found, re-run imessage_search_contacts to get the current id and retry.

• No delete/merge tools: intentionally out of scope, since this is meant to be low-risk to run against real data.

• imessage_send_message group chat support: only works for an existing group chat identifier; it won't create a new group.

• Requires macOS Messages/Contacts apps to be installed and signed in; no support for other platforms.

Notes on implementation

• Message dates in chat.db are nanoseconds since 2001-01-01 (Apple's Core Data epoch); dates.py handles the conversion to/from ISO8601.

• Structured Contacts.app output is parsed out of AppleScript using ASCII separator control characters (record/group/unit/field separators) generated at runtime via (ASCII character N), rather than hand-built JSON in AppleScript. These are generated at runtime rather than embedded as literal bytes in the script source, because Python's str.splitlines() (used to break a script into -e arguments) treats \x1c/\x1d/\x1e as line boundaries and would silently corrupt them.

• All dynamic values (search queries, addresses, phone numbers) are passed as argv items to osascript, never interpolated into the script source, to avoid AppleScript injection.

• Sender identity in imessage_list_messages comes from the handle table (message.handle_id → handle.id); the raw handle is then reverse-resolved to a Contacts.app name by dumping the address book once (bulk AppleScript accessors, cached ~60s) and matching phones on their trailing 10 digits. Name resolution needs Automation permission; if that's missing the read still succeeds and falls back to the raw handle.