imessage-mcp

imessage-mcp

An MCP server that gives AI assistants like Claude Code the ability to read and send iMessages on macOS.

Phone numbers and email addresses are automatically resolved to real names from your Apple Contacts — so you interact with people, not handles.

What it looks like

> imessage-mcp chats 3

1. Sarah, Mike, Pete, Joel
   Chat ID: 91 | iMessage, 4 participants | 46 messages | Mar 15, 9:33 PM
2. Family Group Chat
   Chat ID: 40 | iMessage, 8 participants | 125 messages | Mar 15, 6:08 PM
3. Alex Johnson (+15551234567)
   Chat ID: 67 | iMessage | 12 messages | Mar 15, 4:39 PM

> imessage-mcp messages 67 3

[Mar 15, 2:01 PM] Alex Johnson (+15551234567): Are we still on for Friday?
[Mar 15, 2:05 PM] Me: Yes! Looking forward to it.
[Mar 15, 4:39 PM] Alex Johnson (+15551234567): Great, see you then!

Prerequisites

macOS only. This reads the local Messages database directly.

1. Full Disk Access — your terminal app needs permission to read ~/Library/Messages/chat.db
   • System Settings → Privacy & Security → Full Disk Access → add your terminal (Terminal.app, iTerm2, Ghostty, etc.)
   • Restart the terminal after granting access
2. Contacts permission (optional but recommended) — for resolving phone numbers to names
   • If names aren't showing up, grant Contacts access to your terminal app in System Settings
3. Messages.app signed in — required only for sending messages
4. Node.js >= 22 — uses the built-in node:sqlite module (no native compilation needed)

Run imessage-mcp status to verify everything is working.

Installation

Claude Code plugin (recommended)

Install directly from this repo:

claude plugin add daveremy/imessage-mcp

Or from the daveremy-plugins marketplace (includes all daveremy plugins):

claude plugin add daveremy/claude-plugins --name imessage-mcp

Restart Claude Code and the im_* tools will appear automatically.

Manual MCP config

Alternatively, add to your project's .mcp.json or ~/.claude/mcp.json:

{
  "mcpServers": {
    "imessage-mcp": {
      "command": "npx",
      "args": ["-y", "@daveremy/imessage-mcp"]
    }
  }
}

As a CLI tool

npx @daveremy/imessage-mcp status       # verify access
npx @daveremy/imessage-mcp chats        # list recent conversations
npx @daveremy/imessage-mcp messages 42  # read messages from chat 42

Tools

im_status

Check that database access and contact resolution are working.

Messages database: OK
  Chats: 102
  Messages: 1432

Contacts: OK (77 contacts)

im_chats

List recent conversations, ordered by last activity. Groups show the group name or resolved participant names. 1:1 chats show the contact name with handle.

Parameter	Type	Default	Description
limit	number	20	Maximum chats to return

im_messages

Read messages from a specific chat in chronological order. Includes reactions, attachments, edited/unsent indicators, and pagination.

Parameter	Type	Default	Description
chatId	number	required	Chat ID from im_chats
limit	number	50	Messages per page
cursor	string	—	Opaque cursor from previous response for loading older messages

Messages are formatted as:

[Mar 15, 2:01 PM] Contact Name (+15551234567): message text
[Mar 15, 2:05 PM] Me: response text
[Mar 15, 2:06 PM] Me: [Liked "message text"]
[Mar 15, 2:07 PM] Contact Name (+15551234567): photo.jpg [Attachment: photo.jpg, 2.1 MB]

im_search

Search message text across all chats or within a specific chat. Scans up to 5,000 recent messages with case-insensitive substring matching.

Parameter	Type	Default	Description
query	string	required	Text to search for
chatId	number	—	Limit search to one chat
limit	number	20	Maximum results

Results include a completeness line: (searched 1432 of 1432 total messages) so you know the coverage.

im_send

Send a message to an existing chat. The MCP tool description includes a warning to always confirm with the user before sending.

Parameter	Type	Default	Description
chatId	number	required	Chat ID from im_chats
text	string	required	Message text

Uses JXA (JavaScript for Automation) to send via Messages.app. Only targets existing chat threads by GUID — never creates new conversations.

im_participants

List everyone in a chat with resolved contact names and service type (iMessage, SMS, RCS).

Parameter	Type	Default	Description
chatId	number	required	Chat ID from im_chats