imessage-query-fastmcp-mcp-server

Integrations

  • Provides read-only access to the macOS iMessage database, allowing queries of message history with specific phone numbers, including message text, timestamps, and attachment information with support for date range filtering.

  • Leverages macOS-specific features to access the local iMessage database, enabling search and retrieval of message content while maintaining proper phone number validation and safe attachment handling.

iMessage Query MCP Server

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.

📋 System Requirements

  • macOS (required for iMessage database access)
  • Python 3.6+

📦 Dependencies

Install all required dependencies:

# Using pip pip install -r requirements.txt

Required Packages

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

All dependencies are specified in requirements.txt for easy installation.

📑 Table of Contents

🛠️ MCP Tools

The server exposes the following tools to LLMs:

get_chat_transcript

Retrieve message history for a specific phone number with optional date filtering. Includes:

  • Message text and timestamps
  • Attachment information (if any)
  • Proper phone number validation
  • Date range filtering

🚀 Getting Started

Clone the repository:

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

📦 Installation Options

You can install this MCP server in either Claude Desktop or the Cline VSCode plugin. Choose the option that best suits your needs.

Option 1: Install for Claude Desktop

Install using FastMCP:

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

Option 2: 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 this repository (e.g., /Users/username/Projects/imessage-query-fastmcp-mcp-server)

🔒 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

📚 Development Documentation

The repository includes documentation files for development:

  • dev_docs/imessagedb-documentation.txt: Contains comprehensive documentation about the iMessage database structure and the imessagedb library's capabilities.

This documentation serves as context when developing features and can be used with LLMs to assist in development.

⚙️ Environment Variables

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

-
security - not tested
F
license - not found
-
quality - not tested

local-only server

The server can only run on the client's local machine because it depends on local resources.

An MCP server that provides safe access to your iMessage database through MCP, enabling LLMs to query and analyze iMessage conversations with proper phone number validation and attachment handling

  1. 📋 System Requirements
    1. 📦 Dependencies
      1. Required Packages
    2. 📑 Table of Contents
      1. 🛠️ MCP Tools
        1. get_chat_transcript
      2. 🚀 Getting Started
        1. 📦 Installation Options
          1. Option 1: Install for Claude Desktop
          2. Option 2: Install for Cline VSCode Plugin
        2. 🔒 Safety Features
          1. 📚 Development Documentation
            1. ⚙️ Environment Variables

              Related MCP Servers

              • -
                security
                F
                license
                -
                quality
                An MCP server that enables communication with users through Telegram. This server provides a tool to ask questions to users and receive their responses via a Telegram bot.
                Last updated -
                1
                16
                JavaScript
              • -
                security
                A
                license
                -
                quality
                A server for the Machine Chat Protocol (MCP) that provides a YAML-based configuration system for LLM applications, allowing users to define resources, tools, and prompts without writing code.
                Last updated -
                5
                Python
                MIT License
              • -
                security
                F
                license
                -
                quality
                An MCP server that allows Claude and other LLMs to manage persistent memories across conversations through text file storage, enabling commands to add, search, delete and list memory entries.
                Last updated -
                2
                TypeScript
              • A
                security
                A
                license
                A
                quality
                An MCP server that enables LLMs to perform blockchain operations on the Base network through natural language commands, including wallet management, balance checking, and transaction execution.
                Last updated -
                4
                4
                1
                TypeScript
                MIT License
                • Apple

              View all related MCP servers

              ID: a3k5abmy43