iMessage MCP Server
# imessage-mcp
MCP server that exposes iMessage read/send capabilities on macOS. Runs on a Mac with Messages.app and can be accessed remotely via SSH over Tailscale.
## Tools
| Tool | Description |
|------|-------------|
| `list_conversations` | List recent conversations with last message preview |
| `get_messages` | Get messages from a specific conversation |
| `search_messages` | Full-text search across all messages |
| `get_contact_info` | Look up contact stats by phone/email |
| `send_message` | Send an iMessage to a phone number or email |
| `send_group_message` | Send a message to a named group chat |
## Setup (local)
```bash
uv run imessage-mcp
```
Requires macOS with Messages.app and Full Disk Access for the terminal process.
## Claude Code config (local)
```json
{
"mcpServers": {
"imessage": {
"command": "uv",
"args": ["--directory", "/path/to/imessage-mcp", "run", "imessage-mcp"]
}
}
}
```
## Claude Code config (remote via SSH)
From any device on the Tailscale network:
```json
{
"mcpServers": {
"imessage": {
"command": "ssh",
"args": [
"mba-server",
"/Users/viraat/.local/bin/uv --directory /Users/viraat/Documents/imessage-mcp run imessage-mcp"
]
}
}
}
```
This pipes MCP stdio through SSH — the server runs on the Mac, reads chat.db, and sends via AppleScript.
TDQS
Scored across 6 tools
Each tool has a clearly distinct purpose: get_contact_info retrieves contact details, get_messages fetches conversation history, list_conversations shows recent chats, search_messages performs text searches, send_message sends to individuals, and send_group_message sends to groups. No overlap exists between these functions.
All tools follow a consistent verb_noun naming pattern (e.g., get_contact_info, send_message, list_conversations). The naming is uniform throughout, using snake_case and clear action descriptors without any deviations.
With 6 tools, this server is well-scoped for iMessage functionality, covering key operations like reading, sending, searching, and listing without being overly complex or too sparse. Each tool serves a specific and necessary role.
The toolset provides strong coverage for core iMessage tasks, including sending, receiving, searching, and listing. A minor gap exists in update or delete operations (e.g., editing or deleting messages), but agents can still handle most workflows effectively.