iMessage Query

Provides safe access to the iMessage database for querying conversations and attachments via MCP.

python

0

GitHub Stars

python

Language

7 months ago

First Indexed

3 months ago

Catalog Refreshed

Documentation & install

Readme and setup notes from the catalogue, plus a client-ready config you can copy for your MCP host.

Installation

Add the following to your MCP client configuration file.

Configuration

View docs

{
  "mcpServers": {
    "mcp-mirror-hannesrudolph_imessage-query-fastmcp-mcp-server": {
      "command": "uv",
      "args": [
        "run",
        "--with",
        "fastmcp",
        "fastmcp",
        "run",
        "/path/to/repo/imessage-query-server.py"
      ]
    }
  }
}

This MCP server lets you query your iMessage database safely via the Model Context Protocol. It provides a structured way for LLMs to retrieve conversations and attachments, with phone number validation and careful access controls to keep your data secure.

How to use

You will run this MCP server locally and connect to it from an MCP client. Use the available tool to fetch chat transcripts by phone number, with optional date filtering and attachment details. The server validates numbers, enforces read-only access to the iMessage database, and returns structured results suitable for LLM analysis.

How to install

Prerequisites you need before installing the MCP server: macOS (required to access the iMessage database), Python 3.6 or newer, and a working internet connection to fetch dependencies.

pip install -r requirements.txt

Configuration and deployment

You can deploy the MCP server in two ways. Choose the option that best fits your workflow.

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

Option 2: VSCode Cline plugin configuration

If you are using the Cline VSCode plugin, add the following MCP settings to your workspace configuration. Update the path to where you cloned the project.

{
  "imessage-query": {
    "command": "uv",
    "args": [
      "run",
      "--with",
      "fastmcp",
      "fastmcp",
      "run",
      "/path/to/repo/imessage-query-server.py"
    ]
  }
}

Safety features

The server operates with read-only access to the iMessage database, validates phone numbers, handles attachments safely with missing-file detection, and provides progress suppression for clean JSON responses.

Environment and runtime notes

No additional environment variables are required. The server locates the iMessage database in its default macOS location.

Troubleshooting

If you encounter issues starting the server, ensure Python 3.6+ is installed, dependencies are installed via the requirements file, and the path to the server script is correct in your MCP client configuration.

Examples of usage patterns

Retrieve transcripts for a specific number with an optional date range. - Inspect message text, timestamps, and attachment metadata in a structured response. - Rely on the phone-number validation to avoid invalid matches.

Available tools

get_chat_transcript

Retrieve message history for a specific phone number with optional date filtering. Returns message text, timestamps, and attachment information with proper phone number validation and date range support.