Overview

The iMessage Query MCP Server enables AI assistants to access and analyze your iMessage conversations through a secure Model Context Protocol (MCP) interface. This tool is particularly useful for retrieving conversation history with specific contacts, analyzing message patterns, and accessing message content including attachments.

System Requirements

• macOS (required for iMessage database access)
• Python 3.6 or higher

Installation

Prerequisites

Before installing the iMessage Query MCP Server, ensure you have Python 3.6+ installed on your macOS system.

Step 1: Clone the Repository

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

Step 2: Install Dependencies

Install all required dependencies using pip:

pip install -r requirements.txt

The main dependencies include:

• fastmcp: Framework for building Model Context Protocol servers
• imessagedb: Python library for accessing the macOS Messages database
• phonenumbers: Google's phone number handling library for validation and formatting

Step 3: Choose Your Installation Method

Option A: Install for Claude Desktop

If you're using Claude Desktop, install the MCP server using FastMCP:

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

Option B: 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-server.py"
    ]
  }
}

Replace /path/to/repo with the full path to where you cloned the repository.

Available Tools

get_chat_transcript

This tool retrieves message history for a specific phone number with optional date filtering.

Parameters:

• phone_number: The contact's phone number to retrieve messages from
• start_date (optional): Filter messages starting from this date (format: YYYY-MM-DD)
• end_date (optional): Filter messages up to this date (format: YYYY-MM-DD)

Returns:

• Message text and timestamps
• Attachment information (if any)
• Properly formatted conversation history

Usage Examples

Here are some examples of how to use the iMessage Query MCP Server with an AI assistant:

1. Retrieve recent messages from a contact: "Can you show me my recent messages with John at 555-123-4567?"

2. Find messages within a date range: "Show me my conversation with 555-987-6543 between January 1, 2023 and February 15, 2023."

3. Analyze conversation patterns: "Can you analyze my messaging patterns with 555-555-5555 over the last month?"

Safety Features

The iMessage Query MCP Server includes several 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

Troubleshooting

If you encounter issues:

1. Database Access Problems: Ensure your macOS user has permission to access the Messages database
2. Phone Number Format Issues: Make sure to use standard phone number formats (e.g., +1-555-123-4567)
3. Missing Messages: Check that the date range is correct and that messages exist for the specified contact

For additional help, refer to the development documentation in the dev_docs folder of the repository.