imessage-query-fastmcp-mcp-server

iMessage Query MCP Server is a server that provides secure access to the iMessage database through the Model Context Protocol (MCP). It is built on the FastMCP framework and the imessagedb library, and is designed to enable large language models (LLMs) to query and analyze iMessage conversations while ensuring correct phone number validation and attachment handling.

Purpose

The main purpose of this server is to serve as an MCP server, providing LLMs with an interface to access the iMessage database so they can query and analyze iMessage conversations. It is suitable for scenarios that require an AI assistant to read or analyze the content of iMessage messages, such as integration in Claude Desktop or the Cline VSCode extension.

Main Capabilities

The server exposes a tool get_chat_transcript, used to retrieve the message history for a specific phone number. This tool supports optional date filtering, and the returned messages include the message text, timestamp, and attachment information (if any). In addition, the server also has the following capabilities:

• Uses the phonenumbers library for phone number validation and formatting.
• Secure attachment handling, including detection of missing files.
• Date range validation.
• Suppresses progress output to provide clean JSON responses.

Usage

System Requirements

• macOS (required to access the iMessage database)

Dependencies

• 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, used for correct number validation and formatting. All dependencies are specified in requirements.txt for easy installation.

Installation Options

Option 1: Install for Claude Desktop

Install using FastMCP.

Option 2: Install for the Cline VSCode Extension

In VSCode, click the server icon (☰) in the Cline extension sidebar, then click the "Edit MCP Settings" button (✎), and add the following configuration to the settings file (replace /path/to/repo with the full path to the cloned repository, for example /Users/username/Projects/imessage-query-fastmcp-mcp-server):

{
  "mcpServers": {
    "imessage-query": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/hannesrudolph/imessage-query-fastmcp-mcp-server",
        "imessage-query-fastmcp-mcp-server"
      ]
    }
  }
}

Environment Variables

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

Applicable Scenarios

• Integration in Claude Desktop or the Cline VSCode extension to enable LLMs to query and analyze iMessage conversations.
• Development or analysis tasks that require secure, read-only access to the iMessage database.
• iMessage data queries that require phone number validation and attachment handling.

Limitations

• Only supports macOS, because iMessage database access requires macOS.
• The server provides read-only access and cannot modify the database.
• Requires cloning the repository and configuring paths, which may be somewhat challenging for users unfamiliar with the command line.
• For specific installation steps and configuration details, please refer to the repository documentation.