imessage-mcp

imessage-mcp is a Model Context Protocol (MCP) server for reading iMessage data on macOS. The project is maintained by wyattjoh, hosted on GitHub, uses a Deno monorepo structure, and contains two packages: @wyattjoh/imessage and @wyattjoh/imessage-mcp.

Purpose: This tool is designed to enable LLMs (large language models) to access local iMessage data through the MCP protocol, implementing features such as message search, retrieving chat lists, and contact lookup. It provides read-only access only, cannot send or modify messages, and only accesses local data.

Main capabilities:

• Search messages by text content, contact, or date range
• Get recent messages
• List all chats/conversations
• Get all contacts/handles
• Retrieve messages from a specific chat
• Search macOS contacts by name and associate iMessage handle IDs

Usage: Environment requirements: macOS (iMessage is macOS-only), Deno 2.x or later, read permission for ~/Library/Messages/chat.db or a custom database configured via IMESSAGE_DB_PATH, and read permission for ~/Library/Application Support/AddressBook/ (for contact search).

Installation and running:

• For Claude Desktop app integration, add configuration in claude_desktop_config.json.
• A read-only SQLite database in another location can be opened by setting the IMESSAGE_DB_PATH environment variable, for example a periodically refreshed chat.db snapshot. The process needs read permission for that custom file. If Deno does not have permission to read IMESSAGE_DB_PATH, or if the variable is empty or unset, the library will use ~/Library/Messages/chat.db without prompting for environment access.
• Run from source: clone the repository, install dependencies (deno cache src/index.ts), run the server (deno run --allow-read --allow-env --allow-sys --allow-ffi src/index.ts or use the task deno task start).

Available tools:

• search_messages: Search messages, supporting filters: query (optional, search text), handle (optional, filter by phone number or email), startDate (optional, ISO datetime string, start date), endDate (optional, ISO datetime string, end date), limit (optional, maximum number of results 1-200, default 100), offset (optional, pagination offset, default 0).
• get_recent_messages: Get recent messages, parameters: limit (optional, number of messages 1-100, default 20), offset (optional, pagination offset, default 0).
• get_chats: List all conversations, parameters: limit (optional, number of chats 1-200, default 50), offset (optional, pagination offset, default 0).
• get_handles: Get all contacts/handles, parameters: limit (optional, number of handles 1-200, default 100), offset (optional, pagination offset, default 0).
• get_messages_from_chat: Get messages from a specific chat, parameters: chatGuid (required, chat GUID), limit (optional, number of messages 1-200, default 50), offset (optional, pagination offset, default 0).
• search_contacts: Search macOS contacts by name and get phone numbers, parameters: firstName (required, first name, such as 'John'), lastName (optional, last name, such as 'Smith'; if omitted, search all name fields), limit (optional, maximum number of results 1-200, default 50), offset (optional, pagination offset, default 0). Returns contact information including phone numbers and email addresses, which can be used as the handle parameter. This feature directly searches the macOS AddressBook database to improve performance and reliability.

Pagination: All tools support pagination using the limit and offset parameters and return pagination metadata. The response format returned by all paginated tools includes metadata to help users understand the total number of results without retrieving all of them, determine whether there areWhether there are more pages (hasMore), calculate the current page and total number of pages, and build the pagination UI component.

Use cases: Suitable for scenarios that require accessing iMessage data on macOS through an LLM or MCP client, such as building applications for chat history analysis, contact lookup, message retrieval, and so on.

Limitations:

• Only supports the macOS system.
• Provides read-only access only; messages cannot be sent or modified.
• Only accesses local data.
• Requires Deno 2.x or later.
• Requires the corresponding file read permissions.

Other information: This project is a Deno workspace monorepo; all commands run from the root directory affect all packages. For detailed documentation on each package, please refer to the full documentation in the repository.