iMessage MCP
Read-only MCP server for searching and reading your macOS iMessage history and Contacts.
Add to your client
Copy the config for your MCP client and paste it into its config file.
deno install --global --allow-read --allow-env --allow-sys --allow-ffi -n imessage-mcp jsr:@wyattjoh/imessage-mcpPaste into ~/Library/Application Support/Claude/claude_desktop_config.json
{
"mcpServers": {
"imessage-mcp": {
"command": "deno",
"args": [
"run",
"--allow-read",
"--allow-env",
"--allow-sys",
"--allow-ffi",
"jsr:@wyattjoh/imessage-mcp"
]
}
}
}Step-by-step guides: Add to Claude Desktop · Add to Cursor · Add to Windsurf
Before you start
- macOS (iMessage is only available on macOS)
- Deno 2.x or later
- Read access to ~/Library/Messages/chat.db
- Read access to ~/Library/Application Support/AddressBook/ (for contacts search)
About iMessage MCP
A Deno/TypeScript MCP server that exposes read-only access to macOS iMessage data. It is part of a monorepo alongside the @wyattjoh/imessage core library, and provides tools to search messages, list chats and handles, fetch messages from a specific chat, and search the macOS AddressBook for contacts and their iMessage handle IDs. All tools support limit/offset pagination and return pagination metadata (total, hasMore, page, totalPages).
Tools & capabilities (6)
search_messagesSearch messages with optional filters: query text, handle (phone/email), startDate and endDate (ISO datetime), plus limit (1-200, default 100) and offset for pagination.
get_recent_messagesGet the most recent messages, with limit (1-100, default 20) and offset pagination.
get_chatsList all conversations/chats, with limit (1-200, default 50) and offset pagination.
get_handlesGet all contacts/handles, with limit (1-200, default 100) and offset pagination.
get_messages_from_chatGet messages from a specific chat identified by chatGuid (required), with limit (1-200, default 50) and offset pagination.
search_contactsSearch the macOS AddressBook by firstName (required) and optional lastName, returning contact info with phone numbers and email addresses usable as handle parameters. Supports limit (1-200, default 50) and offset pagination.
What this server can do
iMessage MCP provides tools for these capabilities — tap one to see every MCP server that does the same:
When to use it
- Let an assistant search your iMessage history for a specific topic, person, or time range
- Summarize or review recent messages and conversations
- Look up a contact's phone number or email and correlate it with their iMessage handle
- Pull the full thread of a specific chat for analysis or recall
Security notes
Runs with read-only access to the local iMessage database; no messages can be sent or modified, and only local data is accessed. Requires read access to ~/Library/Messages/chat.db and ~/Library/Application Support/AddressBook/ (typically needs Full Disk Access on macOS). Exposes private message history to the connected LLM, so use with care.
iMessage MCP FAQ
Can it send or modify messages?
No. The server has read-only access to the local iMessage database; no messages can be sent or modified, and it only accesses local data.
What permissions does it need on macOS?
Read access to ~/Library/Messages/chat.db and ~/Library/Application Support/AddressBook/. On macOS this generally requires granting Full Disk Access to the process running Deno.
How do I run it without installing globally?
Run it directly from JSR: deno run --allow-read --allow-env --allow-sys --allow-ffi jsr:@wyattjoh/imessage-mcp
Does it support pagination?
Yes. Every tool accepts limit and offset parameters and returns pagination metadata including total, hasMore, page, and totalPages.
Alternatives to iMessage MCP
Compare all alternatives →
Connect your personal WhatsApp: search, read and send messages and media locally
Powerful Slack MCP with stdio/SSE/HTTP, DMs, group DMs and no-admin token auth
Full Telegram user-account MCP via MTProto: read chats, manage groups, send messages