imessage-query-fastmcp-mcp-server

# Securely Expose iMessage Data to LLMs: An MCP Server for Context-Aware AI

Unlock the power of your iMessage history for Large Language Models (LLMs) with this robust and secure Model Context Protocol (MCP) server. Built upon the FastMCP framework and the `imessagedb` library, this server provides a controlled and validated interface for LLMs to query and analyze your iMessage conversations, enabling context-rich AI applications.

## Core Functionality

This server empowers LLMs with the ability to:

*   **Retrieve iMessage Transcripts:** Obtain message history for specific phone numbers, filtered by date ranges.
*   **Access Attachment Information:** Identify and understand attachments associated with messages.
*   **Validate Phone Numbers:** Ensure data integrity through rigorous phone number validation.

## 🛡️ Prioritizing Security and Privacy

This implementation emphasizes security and privacy through:

*   **Read-Only Access:** The server operates with read-only access to the iMessage database, preventing any modifications.
*   **Phone Number Validation:** The `phonenumbers` library ensures accurate and validated phone number handling.
*   **Safe Attachment Handling:** The server detects and handles missing attachment files gracefully.
*   **Date Range Validation:** Input date ranges are validated to prevent unexpected queries.
*   **Clean JSON Responses:** Progress output is suppressed to ensure clean and parsable JSON responses for LLMs.

## 🛠️ Key Technologies

*   **Model Context Protocol (MCP):** A standardized protocol for connecting LLMs to external data sources and tools.
*   **FastMCP:** A framework for building MCP-compliant servers.
*   **imessagedb:** A Python library for accessing and querying the macOS Messages database.
*   **phonenumbers:** Google's library for parsing, formatting, and validating international phone numbers.

## ⚙️ System Requirements

*   **Operating System:** macOS (required for iMessage database access)
*   **Python Version:** Python 3.6+

## 📦 Installation

1.  **Clone the Repository:**

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

2.  **Install Dependencies:**

    ```bash
    pip install -r requirements.txt
    ```

## 🚀 Deployment Options

### 1. Claude Desktop Integration

Leverage FastMCP for seamless integration with Claude Desktop:

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

2. Cline VSCode Plugin Integration

Integrate with the Cline VSCode plugin for a streamlined development experience:

1. Open the Cline plugin sidebar in VSCode.

2. Click "Edit MCP Settings."

3. Add the following configuration, replacing /path/to/repo with the actual path to your cloned repository:

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

📚 Development Resources

The dev_docs/imessagedb-documentation.txt file provides comprehensive documentation on the iMessage database structure and the imessagedb library, serving as valuable context for development and integration with LLMs.

⚙️ Configuration

This server automatically locates the iMessage database in its default macOS location, eliminating the need for environment variables.

🔑 MCP Tool: get_chat_transcript

This tool is exposed to LLMs, enabling them to retrieve iMessage history with the following features:

• Functionality: Retrieves message history for a specified phone number.
• Filtering: Supports date range filtering for targeted data retrieval.
• Data Points: Includes message text, timestamps, and attachment information.
• Validation: Performs phone number validation to ensure data accuracy.

This MCP server provides a secure and efficient way to connect LLMs with your iMessage data, opening up new possibilities for context-aware AI applications while prioritizing your privacy and security.