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

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.

| Parameter | Type | Description | |---|---|---| | limit | number | Max conversations to return (default: 20) |

get_messages

Get messages from a specific conversation.

| Parameter | Type | Description | |---|---|---| | chat_id | string | Required. Chat ID from get_conversations | | limit | number | Max messages to return (default: 50) |

search_messages

Search across all messages by text.

| Parameter | Type | Description | |---|---|---| | query | string | Required. Text to search for | | limit | number | Max results to return (default: 20) |

get_chat_participants

Get the participants in a conversation.

| Parameter | Type | Description | |---|---|---| | chat_id | string | Required. Chat ID from get_conversations |

send_message

Send an iMessage or SMS.

| Parameter | Type | Description | |---|---|---| | recipient | string | Required. Phone number, email, or contact name | | message | string | Required. Text to send |

get_attachments

List attachments from a conversation.

| Parameter | Type | Description | |---|---|---| | chat_id | string | Required. Chat ID from get_conversations | | limit | number | Max attachments to return (default: 20) |

save_attachment

Save an attachment from a message to disk.

| Parameter | Type | Description | |---|---|---| | attachment_id | string | Required. Attachment ID from get_attachments | | destination | string | Required. Full path where the file should be saved |

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)