💬 iMessage MCP Server

Access your iMessage conversations through the Model Context Protocol

Read, search, and send iMessages directly from Claude, Cursor, or any MCP-compatible client.
No external servers required — works locally with your iMessage database.

⚠️ 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

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.

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:

{
  "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

📥 Message Tools

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

💬 Conversation Tools

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

📎 Attachment Tools

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

🧪 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.

iMessage MCP Server