📌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 that provides safe access to your iMessage database through Model Context Protocol (MCP). It is built with the FastMCP framework and the imessagedb library, allowing LLMs to query iMessage conversations with proper phone number validation and attachment handling.

System Requirements

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

Dependencies

Install required dependencies:

pip install -r requirements.txt

Required Packages

• fastmcp: Framework for building Model Context Protocol servers
• imessagedb: Library for accessing the macOS Messages database
• phonenumbers: Library for phone number validation and formatting

Table of Contents

• System Requirements
• Dependencies
• MCP Tools
• Getting Started
• Installation Options
• Safety Features
• Development Documentation
• Environment Variables

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, including:

• Message text and timestamps
• Attachment information
• Proper 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

You can install this MCP server in either Claude Desktop or the Cline VSCode plugin.

Option 1: Install for Claude Desktop

Install using FastMCP:

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

Option 2: Install for Cline VSCode Plugin

1. In VSCode, click the server icon in the Cline plugin sidebar.
2. Click "Edit MCP Settings."
3. Add the following configuration to the settings file:

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

Replace /path/to/repo with the full path to your cloned repository.

Safety Features

• Read-only access to the iMessage database
• Phone number validation
• Safe attachment handling
• Date range validation
• Progress output suppression for clean JSON responses

Development Documentation

Includes documentation files for development, specifically related to the iMessage database structure.

Environment Variables

No environment variables are required as the server automatically locates the iMessage database in the default macOS location.