Provides tools for reading, searching, and sending iMessages, including support for text messages, attachments, group chats, and conversation management through direct access to the local macOS iMessage database.
💬 iMessage MCP Server
Access your iMessage conversations through the Model Context Protocol
⚠️ 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
📥 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
💬 Conversations
View full chat history with any contact
See recent conversations at a glance
Support for group chats
Track read/unread status
📤 Send Messages
Send text messages to any contact
Share images and files
Send multiple attachments at once
Works with phone numbers and emails
📎 Attachments
Browse messages with attachments
Get attachment metadata (size, type, path)
Filter for images only
View all attachments in a conversation
🚀 Quick Start
Prerequisites
macOS with iMessage configured
Node.js 18 or later
Full Disk Access permission (see below)
Installation
Granting Full Disk Access
The MCP server needs permission to read your iMessage database.
Open System Settings → Privacy & Security → Full Disk Access
Click the + button
Add your terminal app (Terminal, Claude Desktop, Cursor, Warp, VS Code, Ghostyy, etc.)
Restart the application
🔧 Configuration
Claude Desktop
Add to ~/Library/Application Support/Claude/claude_desktop_config.json:
Environment Variables
Variable | Description | Default |
| Logging verbosity (
,
,
,
) |
|
| Enable SDK debug mode |
|
🛠️ Available Tools
Tool | Description |
| Get messages with filters (sender, date, service, attachments) |
| Get unread messages grouped by sender |
| Search messages by text content |
| Send a text message |
| Send an image |
| Send a file attachment |
Tool | Description |
| Get full chat history with a contact |
| Overview of recent chats |
| Get messages from a specific chat/group |
Tool | Description |
| Get messages with attachments |
| Get all attachments from a conversation |
| Send multiple files at once |
🧪 Test Client
An interactive CLI is included for testing with the Vercel AI SDK:
Commands: exit • clear • tools
📁 Project Structure
📜 Scripts
Script | Description |
| Compile TypeScript |
| Watch mode |
| Run the MCP server |
| Interactive test client |
| 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.