iMessage MCP Server

# 💬 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 ```bash 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`: ```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: ```bash 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](https://github.com/photon-hq/imessage-kit) for iMessage database access - Uses the [Model Context Protocol](https://modelcontextprotocol.io) by Anthropic - Test client powered by [Vercel AI SDK](https://sdk.vercel.ai) --- ## 📄 License Licensed under the MIT License.