Retrieve message history for a specific phone number with optional date filtering. Includes message text, timestamps, attachment information, and supports proper phone number validation and date range filtering.
The iMessage Query server provides a secure interface for LLMs to access and analyze your macOS Messages database. Built with the FastMCP framework and imessagedb library, it enables AI assistants to retrieve and process your message history with proper phone number validation and attachment handling. This tool maintains privacy and security by implementing read-only access to your messages database, along with robust phone number validation and safe attachment handling. It's designed specifically for macOS users who want to leverage their message history with AI assistants while maintaining control over their personal data.
The iMessage Query server allows AI assistants to safely access and analyze your iMessage conversations on macOS. It provides a structured way to retrieve message history for specific contacts with optional date filtering.
git clone https://github.com/hannesrudolph/imessage-query-fastmcp-mcp-server.git
cd imessage-query-fastmcp-mcp-server
Install all required packages using pip:
pip install -r requirements.txt
The main dependencies include:
You have two options for using this MCP server:
If you're using Claude Desktop, install the server using FastMCP:
fastmcp install imessage-query-server.py --name "iMessage Query"
To use with the Cline VSCode plugin:
Once installed, your AI assistant can access your iMessage history using the get_chat_transcript tool. You can ask questions like:
The tool handles phone number validation automatically and can filter messages by date range when specified.
The iMessage Query server implements several safety measures:
No environment variables are required as the server automatically locates the iMessage database in the default macOS location.