imessage-mcp

An MCP server that connects Claude Desktop to iMessage on macOS — read conversations, search messages, send texts, and access attachments.

Prerequisites

• macOS

• Node.js 18+

• Claude Desktop

• Full Disk Access granted to Claude Desktop (required to read ~/Library/Messages/chat.db)

Granting Full Disk Access

1. Open System Settings → Privacy & Security → Full Disk Access

2. Add Claude to the list and enable it

3. Restart Claude Desktop

Related MCP server: iMessage MCP Server

Installation

1. Add to Claude Desktop config

Open ~/Library/Application Support/Claude/claude_desktop_config.json and add:

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

2. Restart Claude Desktop

Manual install (alternative)

If you prefer to run from source:

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

Then use this config instead:

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

Tools

get_conversations

List recent iMessage conversations.

get_messages

Get messages from a specific conversation.

search_messages

Search across all messages by text.

get_chat_participants

Get the participants in a conversation.

send_message

Send an iMessage or SMS.

get_attachments

List attachments from a conversation.

save_attachment

Save an attachment from a message to disk.

Notes

• Messages are read directly from ~/Library/Messages/chat.db using SQLite — no AppleScript required for reads

• Sending uses AppleScript via osascript

• Contact names are resolved from AddressBook automatically

• US phone numbers are normalized (leading 1 stripped from 11-digit numbers)