Hannesrudolph Imessage Query Fastmcp MCP Server

🚀 iMessage Query MCP Server

An iMessage database server that provides secure access through the Model Context Protocol (MCP). Built with the FastMCP framework and the imessagedb library, this server allows large language models (LLMs) to query and analyze iMessage conversations. It also features proper phone number verification and attachment handling.

🚀 Quick Start

Clone the repository:

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

✨ Features

• Secure access to iMessage database via MCP.
• Allows LLMs to query and analyze iMessage conversations.
• Proper phone number verification and attachment handling.

📦 Installation

System Requirements

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

Dependencies

Install all the required dependencies:

# Using pip
pip install -r requirements.txt

Required Packages

• fastmcp: A framework for building Model Context Protocol servers.
• imessagedb: A Python library for accessing and querying the macOS Messages database.
• phonenumbers: Google's phone number handling library for proper number verification and formatting.

All dependencies are listed in the requirements.txt file for easy installation.

Installation Options

You can install this MCP server in Claude Desktop or the Cline VSCode plugin. Choose the option that suits you best.

Option 1: Installation in Claude Desktop

Install using FastMCP:

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

Option 2: Installation in Cline VSCode Plugin

To use this server with the Cline VSCode plugin:

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

💻 Usage Examples

Basic Usage

The server provides the following tools to the LLM:

get_chat_transcript

Get the chat history for a specific phone number, with optional date filtering. It includes:

• Message text and timestamps.
• Attachment information (if available).
• Proper phone number verification.
• Date range filtering.

🔧 Technical Details

Security Features

• Read-only access to the iMessage database.
• Phone number verification using the phonenumbers library.
• Security checks for attachment handling (missing file detection).
• Date range verification.
• Suppression of progress output to keep the JSON response clean.

📚 Documentation

The repository contains documentation for development:

• dev_docs/imessagedb-documentation.txt: Comprehensive documentation about the iMessage database structure and the functions of the imessagedb library.

This documentation is used as context during development and can be used in conjunction with LLMs to assist in development.

⚙️ Environment Variables

No environment variables need to be set. The server will automatically locate the default iMessage database location on macOS.