iMessage Query MCP Server: Secure Query & Validation

Securely tap into your iMessage data with MCP-powered analysis—LLMs query & validate conversations, attachments, and phone numbers via FastMCP & imessagedb. Streamline insights, safely." )

Visit Repository

✨ Research And Data

4.2(106 reviews)

159 saves

74 comments

Ranked in the top 4% of all AI tools in its category

About iMessage Query MCP Server

What is iMessage Query MCP Server: Secure Query & Validation?

This server enables secure access to macOS iMessage databases using the Model Context Protocol (MCP). Built with the FastMCP framework and imessagedb library, it allows large language models (LLMs) to safely query conversations with robust validation mechanisms. Key features include phone number verification via Google's phonenumbers library and seamless attachment handling—all while maintaining strict read-only database access. Imagine analyzing customer service chats securely without exposing raw message data.

How to Use iMessage Query MCP Server: Secure Query & Validation?

Setup: Clone the repository and install dependencies using pip install -r requirements.txt
Installation Options:
- Claude Desktop: Run fastmcp install imessage-query-server.py --name "iMessage Query"
- VSCode Users: Configure Cline plugin with specified JSON in your settings file
Query Execution: Use the get_chat_transcript tool to retrieve messages with phone number validation and optional date ranges

Note: Always ensure correct file paths when configuring VSCode integration

iMessage Query MCP Server Features

Key Features of iMessage Query MCP Server: Secure Query & Validation

Data Security: Mandatory phone number verification blocks unauthorized access attempts
Temporal Control: Date filtering prevents exposure of irrelevant historical data
Attachment Integrity: Automatic validation of message attachments prevents corruption risks
Framework Compatibility: Seamless integration with existing FastMCP workflows

These safeguards make it ideal for compliance-driven environments like legal teams or enterprise support systems

Use Cases for iMessage Query MCP Server

Organizations leverage this solution in:

Customer Analysis: Retailers analyze support chat patterns without exposing raw messages
Legal Compliance: Law firms extract timestamped evidence with verified communication trails
AI Training: Enterprises securely feed validated chat data to improve chatbot accuracy

iMessage Query MCP Server FAQ

Frequently Asked Questions

Is this compatible with all macOS versions?: Requires macOS 10.15+ to ensure compatibility with modern Python dependencies
How is security maintained?: Three-layer protection: read-only database access, number verification, and attachment checksum validation
What if installation fails?: Verify Python 3.8+ is installed and check firewall settings blocking the phonenumbers API

For advanced troubleshooting, consult the Cline plugin documentation

Content

iMessage Query MCP Server

An MCP server that provides safe access to your iMessage database through Model Context Protocol (MCP). This server is built with the FastMCP framework and the imessagedb library, enabling LLMs to query and analyze iMessage conversations with proper phone number validation and attachment handling.

📋 System Requirements

macOS (required for iMessage database access)
Python 3.6+

📦 Dependencies

Install all required dependencies:

# Using pip
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 proper number validation and formatting

All dependencies are specified in requirements.txt for easy installation.

📑 Table of Contents

System Requirements
Dependencies
MCP Tools
Getting Started
Installation Options
- Claude Desktop
- Cline VSCode Plugin
Safety Features
Development Documentation
Environment Variables

🛠️ MCP Tools

The server exposes the following tools to LLMs:

get_chat_transcript

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

Message text and timestamps
Attachment information (if any)
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. Choose the option that best suits your needs.

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

To use this server with the Cline VSCode plugin:

In VSCode, click the server icon (☰) in the Cline plugin sidebar
Click the "Edit MCP Settings" button (✎)
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 where you cloned this repository (e.g., /Users/username/Projects/imessage-query-fastmcp-mcp-server)

🔒 Safety Features

Read-only access to the iMessage database
Phone number validation using the phonenumbers library
Safe attachment handling with missing file detection
Date range validation
Progress output suppression for clean JSON responses

📚 Development Documentation

The repository includes documentation files for development:

dev_docs/imessagedb-documentation.txt: Contains comprehensive documentation about the iMessage database structure and the imessagedb library's capabilities.

This documentation serves as context when developing features and can be used with LLMs to assist in development.

⚙️ Environment Variables

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