💬 iMessage MCP Server

Access your iMessage conversations through the Model Context Protocol

<p align="center"> <strong>Read, search, and send iMessages</strong> directly from Claude, Cursor, or any MCP-compatible client.<br> No external servers required — works locally with your iMessage database. </p>

⚠️ Local-only server — This MCP server reads directly from local macOS database files (~/Library/Messages/chat.db and ~/Library/Application Support/AddressBook/). It must run on the same Mac where your iMessages are loaded and Apple ID is configured. Remote or cloud deployment is not supported.

---

✨ Features

<table> <tr> <td width="50%">

📥 Read Messages

• Get recent messages with smart filtering
• View unread messages grouped by sender
• Search across all conversations
• Filter by date, service (iMessage/SMS), attachments

</td> <td width="50%">

💬 Conversations

• View full chat history with any contact
• See recent conversations at a glance
• Support for group chats
• Track read/unread status

</td> </tr> <tr> <td width="50%">

📤 Send Messages

• Send text messages to any contact
• Share images and files
• Send multiple attachments at once
• Works with phone numbers and emails

</td> <td width="50%">

📎 Attachments

• Browse messages with attachments
• Get attachment metadata (size, type, path)
• Filter for images only
• View all attachments in a conversation

</td> </tr> </table>

---

🚀 Quick Start

Prerequisites

• macOS with iMessage configured
• Node.js 18 or later
• Full Disk Access permission (see below)

Installation

git clone https://github.com/sameelarif/imessage-mcp.git
cd imessage-mcp
pnpm install
pnpm build

Granting Full Disk Access

The MCP server needs permission to read your iMessage database.

1. Open System Settings → Privacy & Security → Full Disk Access
2. Click the + button
3. Add your terminal app (Terminal, Claude Desktop, Cursor, Warp, VS Code, Ghostyy, etc.)
4. Restart the application

---

🔧 Configuration

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

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

Environment Variables

Variable	Description	Default
LOG_LEVEL	Logging verbosity (debug, info, warn, error)	info
DEBUG	Enable SDK debug mode	false

---

🛠️ Available Tools

<details> <summary><strong>📥 Message Tools</strong></summary>

Tool	Description
get-messages	Get messages with filters (sender, date, service, attachments)
get-unread-messages	Get unread messages grouped by sender
search-messages	Search messages by text content
send-message	Send a text message
send-image	Send an image
send-file	Send a file attachment

</details>

<details> <summary><strong>💬 Conversation Tools</strong></summary>

Tool	Description
get-conversation	Get full chat history with a contact
get-recent-conversations	Overview of recent chats
get-chat-messages	Get messages from a specific chat/group

</details>

<details> <summary><strong>📎 Attachment Tools</strong></summary>

Tool	Description
get-attachments	Get messages with attachments
get-conversation-attachments	Get all attachments from a conversation
send-files	Send multiple files at once

</details>

---

🧪 Test Client

An interactive CLI is included for testing with the Vercel AI SDK:

export OPENAI_API_KEY=sk-...
pnpm test-client

Commands: exit • clear • tools

---

📁 Project Structure

src/
├── index.ts              # MCP server entry point
├── test-client.ts        # Interactive test client
├── tools/
│   ├── messages.ts       # Message tools
│   ├── conversations.ts  # Conversation tools
│   └── attachments.ts    # Attachment tools
└── utils/
    ├── logger.ts         # Pretty CLI logging
    └── sdk.ts            # SDK initialization

---

📜 Scripts

Script	Description
pnpm build	Compile TypeScript
pnpm dev	Watch mode
pnpm start	Run the MCP server
pnpm test-client	Interactive test client
pnpm clean	Remove build artifacts

---

🙏 Acknowledgements

• Built with @photon-ai/imessage-kit for iMessage database access
• Uses the Model Context Protocol by Anthropic
• Test client powered by Vercel AI SDK

---

📄 License

Licensed under the MIT License.