Imessage Query Fastmcp MCP Server

🚀 iMessage Query MCP Server

An iMessage database server that provides secure access through the Model Context Protocol (MCP). This server is built using the FastMCP framework and the imessagedb library, allowing 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

• Provide secure access to the iMessage database through the Model Context Protocol (MCP).
• Allow LLMs to query and analyze iMessage conversations.
• Feature proper phone number verification and attachment handling.

📦 Installation

System Requirements

• macOS (Required for accessing the iMessage database)
• Python 3.6+

Dependencies

Install all the necessary dependencies:

# Using pip
pip install -r requirements.txt

Required Packages

• fastmcp: A library for building the MCP framework.
• 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 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:

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-fastmcp-mcp-server/imessage-query-server.py"
    ]
  }
}

Replace /path/to/repo with the full path of the cloned repository (e.g., /Users/username/Projects/imessage-query-fastmcp-mcp-server).

🛠️ MCP Tools

The server exposes the following tools to LLMs:

get_chat_transcript

Retrieve the message history based on a specific phone number, with optional date filtering. Includes:

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

🔧 Technical Details

• Read-only access to the iMessage database: Ensures data security.
• Phone number verification using the phonenumbers library: Guarantees the accuracy of phone numbers.
• Security in attachment handling: Detects missing files.
• Date range verification: Ensures valid query ranges.
• Suppression of progress output: Keeps JSON responses clean.

📚 Documentation

The repository contains documentation for development:

• dev_docs/imessagedb-documentation.txt: Contains comprehensive documentation on the iMessage database structure and the functions of the imessagedb library.

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