iMessage Query MCP Server

Source

An MCP server that provides safe access to your iMessage database through Model Context Protocol (MCP). This server is built with the FastMCP framework and the imessagedb library, enabling LLMs to query and analyze iMessage conversations with proper phone number validation and attachment handling.

Catalog onlyCatalog onlySTDIO

Overview

The iMessage Query MCP Server is an MCP server that provides safe access to your iMessage database through Model Context Protocol (MCP). Built with the FastMCP framework and the imessagedb library, it allows large language models (LLMs) to query and analyze iMessage conversations while ensuring proper phone number validation and attachment handling.

To use the server, clone the repository from GitHub, install the necessary dependencies, and choose your preferred installation option for either Claude Desktop or the Cline VSCode plugin.

Safe, read-only access to the iMessage database - Support for querying message histories with date filtering - Proper phone number validation with comprehensive handling of attachments - Integration capabilities with LLMs for advanced query capabilities

Analyzing conversation histories for personal insights.
Integrating with AI models to extract useful information from iMessage databases.
Automating the reporting of message trends or statistics over time.

Add to your AI client

Use these steps to connect iMessage Query MCP Server in Cursor, Claude, VS Code, and other MCP-compatible apps. The same JSON appears in the Use with menu above for one-click copy.

Cursor

Add this to your .cursor/mcp.json file in your project root, then restart Cursor.

.cursor/mcp.json

{
  "mcpServers": {
    "imessage-query-fastmcp-mcp-server-hannesrudolph": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-imessage-query-fastmcp-mcp-server-hannesrudolph"
      ]
    }
  }
}

Claude Desktop

Add this server entry to the mcpServers object in your Claude Desktop config, then restart the app.

~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows)

{
  "mcpServers": {
    "imessage-query-fastmcp-mcp-server-hannesrudolph": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-imessage-query-fastmcp-mcp-server-hannesrudolph"
      ]
    }
  }
}

Claude Code

Add this to your project's .mcp.json file. Claude Code will detect it automatically.

.mcp.json (project root)

{
  "mcpServers": {
    "imessage-query-fastmcp-mcp-server-hannesrudolph": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-imessage-query-fastmcp-mcp-server-hannesrudolph"
      ]
    }
  }
}

VS Code (Copilot)

Add this to your .vscode/mcp.json file. Requires the GitHub Copilot extension with MCP support enabled.

.vscode/mcp.json

{
  "servers": {
    "imessage-query-fastmcp-mcp-server-hannesrudolph": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-imessage-query-fastmcp-mcp-server-hannesrudolph"
      ]
    }
  }
}

Windsurf

Add this to your Windsurf MCP config file, then restart Windsurf.

~/.codeium/windsurf/mcp_config.json

{
  "mcpServers": {
    "imessage-query-fastmcp-mcp-server-hannesrudolph": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-imessage-query-fastmcp-mcp-server-hannesrudolph"
      ]
    }
  }
}

Cline

Open Cline settings, navigate to MCP Servers, and add this server configuration.

Cline MCP Settings (via UI)

{
  "mcpServers": {
    "imessage-query-fastmcp-mcp-server-hannesrudolph": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-imessage-query-fastmcp-mcp-server-hannesrudolph"
      ]
    }
  }
}

FAQ

Is this server compatible with all versions of macOS?

Yes, it requires macOS but is compatible with versions supporting the iMessage database.

How do I ensure data security?

The server provides read-only access, ensuring your messages are not altered, along with features for attachment handling that maintans privacy.

Can I query messages without a phone number?

No, proper phone number validation is required for all queries to maintain data integrity.

Research and data