iMessage Query MCP Server

What is iMessage Query MCP Server?

It is an MCP server that provides safe access to your iMessage database through Model Context Protocol. Built with FastMCP and the imessagedb library, it enables LLMs to query and analyze iMessage conversations with proper phone number validation and attachment handling.

How to use iMessage Query MCP Server?

Clone the repository and install dependencies using pip install -r requirements.txt. Then install either for Claude Desktop via fastmcp install imessage-query-server.py --name "iMessage Query" or configure for the Cline VSCode plugin by editing MCP settings with a JSON configuration using uv run fastmcp run /path/to/imessage-query-server.py.

Key features of iMessage Query MCP Server

• Read-only access to the iMessage database
• Phone number validation using the phonenumbers library
• Safe attachment handling with missing file detection
• Date range filtering for message retrieval
• Progress output suppression for clean JSON responses
• Supports both Claude Desktop and Cline VSCode plugin

Use cases of iMessage Query MCP Server

• An LLM can retrieve message history for a specific phone number to assist in conversation analysis
• Query iMessage transcripts with date range filters for time-bounded analysis
• Integrate iMessage data into an AI assistant workflow within Claude Desktop or Cline

FAQ from iMessage Query MCP Server

What kind of data does it access?

It accesses the local macOS iMessage database with read-only permissions, retrieving message text, timestamps, and attachment information.

What are the system requirements?

macOS is required for iMessage database access, and Python 3.6 or higher is needed to run the server.

What dependencies does it use?

It requires fastmcp, imessagedb, and phonenumbers Python packages, all listed in requirements.txt.

How do I install it?

Clone the repository, install dependencies, then use fastmcp install for Claude Desktop or configure MCP settings for the Cline VSCode plugin.

Is there any environment configuration needed?

No environment variables are required; the server automatically locates the iMessage database on macOS.