Secure iMessage Data Access Framework

This specialized Model Context Protocol (MCP) backend furnishes controlled access to the local iMessage storage structure on macOS systems. Leveraging the FastMCP construction kit alongside the imessagedb utility, this server permits Large Language Models (LLMs) to inspect message threads, strictly adhering to validated telephone identifier formats and automating the necessary operating system security affirmations.

📋 Operational Prerequisites

• macOS Requirement: Essential for accessing the underlying Messages database.
• Python Runtime: Version 3.12 or newer (for contemporary language features).
• Package Manager: Deployment mandates the uv utility for rapid dependency resolution.
• Client Authorization: The invoking MCP client (e.g., Cursor, Claude Desktop, VS Code) must possess Full Disk Access privileges.

📦 Required Components

Bootstrap with uv

We employ uv for fast and dependable management of Python packages. Install it initially:

# Recommended installation via Homebrew
brew install uv

# Alternative official installer
curl -LsSf https://astral.sh/uv/install.sh | sh

Python Dependencies

All necessary libraries are managed implicitly by the execution script using internal metadata. No manual installation step is needed for these components:

• fastmcp: The foundational framework for constructing MCP backends.
• imessagedb: The library dedicated to interfacing with and querying the macOS Messages repository.
• phonenumbers: Google's robust library for ensuring accurate validation and standardization of contact identifiers.

Execution via uv handles the automated provisioning of these prerequisites.

📑 Navigational Index

• Operational Prerequisites
• Required Components
• Exposed MCP Functions
• Initiation Sequence
• Deployment Strategies
• For Claude Desktop
• For Cline VSCode Extension
• macOS Security Configuration
• Safety Mechanisms
• Development Context
• Configuration Variables

🛠️ MCP Toolkit Interface

The server exposes the subsequent capabilities to integrated LLM agents:

get_chat_transcript

Fetches the sequential message history pertaining to a designated contact, optionally constrained by temporal boundaries.

Arguments: - phone_number (mandatory): The contact identifier (E.164 format is optimal). - start_date (optional): The commencement point for history retrieval, specified in ISO standard (YYYY-MM-DD). - end_date (optional): The termination point for history retrieval, specified in ISO standard (YYYY-MM-DD).

Capabilities: - Automated validation and normalization of the provided contact number. - Extraction of message content and associated time markers. - Metadata retrieval for embedded media, including detection of missing file references. - Temporal scope filtering (defaults to the preceding seven calendar days if not specified). - Origin identification via the is_from_me status flag.

🚀 Initial Setup

Clone the source repository:

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

📦 Deployment Strategies

This backend can be integrated with Claude Desktop, the Cline VSCode extension, or any compliant MCP client. Select the relevant integration path:

Option 1: Integration with Claude Desktop

1. Locate the Configuration File:
2. Path: ~/Library/Application Support/Claude/claude_desktop_config.json

3. Create this JSON file if absent.

4. Inject Server Definition:

{
  "mcpServers": {
    "imessage-query": {
      "command": "/absolute/path/to/imessage-query-server.py"
    }
  }
}

1. Substitute Placeholder with the actual, complete file system path to your cloned script (e.g., /Users/user_name/Dev/imessage-query-fastmcp-mcp-server/imessage-query-server.py).

2. Refresh Claude Desktop (Quit via Cmd+Q and relaunch).

Option 2: Integration with Cline VSCode Extension

To utilize this service within the Cline VSCode plugin:

1. In the VSCode interface, access the Cline sidebar and click the server configuration icon (☰).
2. Select the "Edit MCP Settings" control (✎).
3. Append the subsequent configuration block to the settings file:

{
  "imessage-query": {
    "command": "/absolute/path/to/imessage-query-server.py"
  }
}

1. Replace the path placeholder with the script's full absolute location.

Option 3: Other MCP Clients

For unsupported clients, invoke the script directly using its absolute path as the execution command:

/absolute/path/to/imessage-query-server.py

The script's interpreter directive (#!/usr/bin/env -S uv run --script) ensures automatic dependency resolution upon execution.

Note: This streamlined setup supersedes prior manual FastMCP installation procedures. The script now manages its entire dependency ecosystem via uv.

🔐 macOS Security Provisioning

This backend mandates Full Disk Access to successfully read the archived Messages data. The system incorporates smart permission verification logic that guides the user through the necessary setup.

Automated Permission Verification

Upon initial invocation, the server will: 1. Identify the invoking client application (e.g., Cursor, Claude Desktop). 2. Check current Full Disk Access status. 3. Programmatically launch System Preferences to the pertinent security panel. 4. Present tailored, step-by-step instructions specific to the discovered application.

Manual Authorization Procedure

If automation fails, follow these manual steps:

1. Navigate to System Preferences → Privacy & Security → Full Disk Access.
2. Unlock modifications by clicking the padlock icon and authenticating.
3. Utilize the '+' button to register a new application.
4. Locate and select the executable for your MCP client:
5. Claude Desktop: /Applications/Claude.app
6. Cursor: /Applications/Cursor.app
7. VS Code: /Applications/Visual Studio Code.app
8. Restart the MCP client application entirely (Quit and Relaunch).

Common Anomalies

• Access Denied Errors: Verify the client application was fully restarted after permission grant.
• uv listed instead of App Name: The system fallback is showing; ensure the actual client app is targeted for permission.
• Database Unreachable: Confirm the Messages application has been launched and iMessage service is active.

Confidentiality Statement

This server interface is strictly confined to read-only operations on the Message archive. Modification, erasure, or transmission of messages are architecturally prohibited.

🔒 Protective Measures

• Immutable Data Access: Enforced read-only policy against the Messages persistence layer.
• Contact Validation: Strict adherence to contact IDs enforced via the Google phonenumbers utility, favoring E.164 standardization.
• Media Safety: Robust handling of embedded attachments, featuring integrity checks and metadata extraction.
• Temporal Query Integrity: Input validation to reject nonsensical date ranges.
• Protocol Cleanliness: Suppression of routine progress reporting to maintain clean JSON output for the MCP layer.
• Guidance Subsystem: Intelligent detection of the client environment for contextually accurate permission setup assistance.
• Client Identification: Mechanism to correctly identify the host application for precise authorization feedback.

📚 Development Resources

Rich contextual material is provided within the source tree to aid in feature enhancement:

• dev_docs/imessagedb-documentation.txt: Comprehensive schema details for the iMessage repository and the imessagedb library capabilities.
• dev_docs/fastmcp-documentation.txt: In-depth information on the FastMCP execution environment and tool definition.
• dev_docs/mcp-documentation.txt: Reference material for the Model Context Protocol specification itself.

This documentation set serves as essential context for development tasks and can be utilized by LLMs to expedite feature implementation.

⚙️ Configuration Parameters

Variable	Purpose	Default Value
SQLITE_DB_PATH	Override path for the SQLite data file	~/Library/Messages/chat.db

The server defaults to the standard macOS Messages data location; this environment variable is reserved for non-standard deployments.

🔧 Advanced Operations

Overriding Database Location

To direct the server to a non-standard database file:

export SQLITE_DB_PATH="/path/to/alternate/chat.db"

Server Verification

Validate server functionality using the mcptools utility (source: github.com/f/mcptools):

# Move into the project directory
cd /path/to/imessage-query-fastmcp-mcp-server

# List accessible functions
mcp tools ./imessage-query-server.py

# Execute a sample function call
mcp call get_chat_transcript ./imessage-query-server.py -p '{"phone_number": "+1234567890"}'

The script automatically triggers dependency installation via uv during its initial launch sequence.

🐛 Diagnostics

Frequently Encountered Errors

Message: "❌ Full Disk Access credential missing" - Consult the macOS Security Configuration guide. - Ensure the invoking client was fully relaunched post-authorization.

Message: "Messages persistence layer inaccessible" - Verify the Messages application has been opened at least once. - Confirm iMessage service is configured and active within Messages preferences.

Message: "Unrecognized contact identifier format" - Validation strictly follows the rules enforced by Google's phonenumbers library. - Strongly consider utilizing the E.164 standard (e.g., "+1234567890"). - Unqualified domestic numbers will be presumed to belong to the primary national dialing code.

Seeking Assistance

If persistent issues arise: 1. Scrutinize the error message for diagnostic clues. 2. Double-check that the MCP application has the requisite Full Disk Access. 3. Confirm basic functionality of the Messages app. 4. Attempt direct server testing using mcptools (refer to Advanced Operations).