📌Overview

Purpose: To provide safe access to the iMessage database through Model Context Protocol (MCP), enabling secure querying and analysis of iMessage conversations.

Overview: The iMessage Query MCP Server utilizes the FastMCP framework and the imessagedb library to enable LLMs to interact with iMessage data. This server supports phone number validation and attachment handling while ensuring a secure querying environment.

Key Features:

• Safe Access: Offers read-only access to the iMessage database, ensuring data integrity while preventing unauthorized modifications.

• Phone Number Validation: Utilizes the phonenumbers library to verify phone numbers, ensuring accurate data retrieval.

• Message History Retrieval: Enables LLMs to access chat transcripts with options for date filtering, including timestamps and attachment details.

---

iMessage Query MCP Server

An MCP server providing safe access to your iMessage database through Model Context Protocol (MCP). Built with the FastMCP framework and the imessagedb library, it enables LLMs to query and analyze iMessage conversations with phone number validation and attachment handling.

System Requirements

• macOS (required for iMessage database access)
• Python 3.6+

Dependencies

Install dependencies using:

pip install -r requirements.txt

Required Packages

• fastmcp: Framework for building Model Context Protocol servers
• imessagedb: Python library for accessing and querying the macOS Messages database
• phonenumbers: Google's phone number handling library for validation and formatting

All dependencies are listed in requirements.txt.

MCP Tools

The server exposes the following tool to LLMs:

get_chat_transcript

Retrieve message history for a specific phone number with optional date filtering. Features include:

• Message text and timestamps
• Attachment information (if any)
• Phone number validation
• Date range filtering

Getting Started

Clone the repository:

git clone https://github.com/hannesrudolph/imessage-query-fastmcp-mcp-server.git
cd imessage-query-fastmcp-mcp-server

Installation Options

Choose one of the following options to install the MCP server:

Option 1: Install for Claude Desktop

fastmcp install imessage-query-server.py --name "iMessage Query"

Option 2: Install for Cline VSCode Plugin

To use this server with the Cline VSCode plugin:

1. In VSCode, open the Cline plugin sidebar and click the server icon (☰)
2. Click the "Edit MCP Settings" button (✎)
3. Add the following configuration to the settings file, replacing /path/to/repo with the repository path on your machine:

{
  "imessage-query": {
    "command": "uv",
    "args": [
      "run",
      "--with",
      "fastmcp",
      "fastmcp",
      "run",
      "/path/to/repo/imessage-query-server.py"
    ]
  }
}

Safety Features

• Read-only access to iMessage database
• Phone number validation via phonenumbers library
• Safe attachment handling with missing file detection
• Date range validation
• Suppression of progress output to produce clean JSON responses

Development Documentation

Development documentation is available in the repository:

• dev_docs/imessagedb-documentation.txt: Documentation on the iMessage database structure and imessagedb library capabilities, useful for feature development and LLM assistance.

Environment Variables

No environment variables are required; the server automatically locates the iMessage database at the default macOS location.