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 automatic macOS permission handling.

📋 System Requirements

• macOS (required for iMessage database access)
• Python 3.12+ (required for modern type hints)
• uv (modern Python package manager)
• Full Disk Access permission for your MCP client (Claude Desktop, Cursor, VS Code, etc.)

📦 Dependencies

Install uv (Required)

This project uses uv for fast, reliable Python package management. Install it first:

# Install uv using Homebrew (recommended)
brew install uv

# Or install using the official installer
curl -LsSf https://astral.sh/uv/install.sh | sh

Python Dependencies

The script automatically manages its dependencies using the embedded metadata. No separate installation needed! Dependencies include:

• 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 automatically installed when the script runs via uv.

📑 Table of Contents

• System Requirements
• Dependencies
• MCP Tools
• Getting Started
• Installation Options
  • Claude Desktop
  • Cline VSCode Plugin
• macOS Permissions Setup
• Safety Features
• Development Documentation
• Environment Variables

🛠️ 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.

Parameters:

• phone_number (required): Phone number in any format (E.164 format preferred)
• start_date (optional): Start date in ISO format (YYYY-MM-DD)
• end_date (optional): End date in ISO format (YYYY-MM-DD)

Features:

• Automatic phone number validation and formatting
• Message text and timestamps
• Attachment information with missing file detection
• Date range filtering (defaults to last 7 days if no dates specified)
• Sender identification (is_from_me flag)

🚀 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 Claude Desktop, Cline VSCode plugin, or any other MCP client. Choose the option that best suits your needs.

Option 1: Claude Desktop

1. Find your Claude Desktop config file:

   • Location: ~/Library/Application Support/Claude/claude_desktop_config.json
   • Create the file if it doesn't exist

2. Add the server configuration:

{
  "mcpServers": {
    "imessage-query": {
      "command": "/full/path/to/imessage-query-server.py"
    }
  }
}

3. Replace the path with the full path to your cloned repository (e.g., /Users/username/Projects/imessage-query-fastmcp-mcp-server/imessage-query-server.py)

4. Restart Claude Desktop completely (Cmd+Q, then relaunch)

Option 2: 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": "/full/path/to/imessage-query-server.py"
  }
}

4. Replace the path with the full path to your cloned repository

Option 3: Other MCP Clients

For other MCP clients, use the direct script path as the command:

/full/path/to/imessage-query-server.py

The script's shebang (#!/usr/bin/env -S uv run --script) handles dependency management automatically.

Note: This simplified configuration replaces the previous FastMCP installation method. The script is now self-contained and manages its own dependencies through uv.

🔐 macOS Permissions Setup

This server requires Full Disk Access permission to read the iMessage database. The server includes intelligent permission detection and will guide you through the setup process.

Automatic Permission Detection

When you first use the server, it will:

1. Detect your MCP client (Claude Desktop, Cursor, VS Code, etc.)
2. Check for Full Disk Access permission
3. Automatically open System Preferences to the correct settings panel
4. Provide step-by-step instructions specific to your application

Manual Permission Setup

If automatic detection doesn't work, follow these steps:

1. Open System Preferences → Privacy & Security → Full Disk Access
2. Click the lock icon and enter your password to make changes
3. Click the '+' button to add an application
4. Navigate to and select your MCP client:
   • Claude Desktop: /Applications/Claude.app
   • Cursor: /Applications/Cursor.app
   • VS Code: /Applications/Visual Studio Code.app
5. Restart your MCP client completely (Cmd+Q, then relaunch)

Common Issues

• Permission denied errors: Make sure you've restarted your MCP client after granting permission
• "uv" instead of app name: The server will auto-detect your actual MCP client and provide correct instructions
• Database not found: Ensure you've used the Messages app and iMessage is enabled

Security Note

This server only requires read access to your iMessage database. It cannot modify, delete, or send messages.

🔒 Safety Features

• Read-only access to the iMessage database (cannot modify, delete, or send messages)
• Phone number validation using Google's phonenumbers library with proper E.164 formatting
• Safe attachment handling with missing file detection and metadata extraction
• Date range validation to prevent invalid queries
• Progress output suppression for clean JSON responses in MCP protocol
• Intelligent permission detection with automatic System Preferences navigation
• MCP client identification for accurate permission guidance

📚 Development Documentation

The repository includes comprehensive documentation for development:

• dev_docs/imessagedb-documentation.txt: Complete documentation about the iMessage database structure and the imessagedb library's capabilities
• dev_docs/fastmcp-documentation.txt: FastMCP framework details and MCP tool development
• dev_docs/mcp-documentation.txt: Model Context Protocol specification

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

⚙️ Environment Variables

Variable	Description	Default
SQLITE_DB_PATH	Custom path to iMessage database	~/Library/Messages/chat.db

The server automatically locates the iMessage database in the default macOS location. The environment variable is only needed for custom database locations.

🔧 Advanced Usage

Custom Database Path

If you need to use a custom database path:

export SQLITE_DB_PATH="/path/to/custom/chat.db"

Testing the Server

Test the server directly using mcptools (github.com/f/mcptools):

# Navigate to the repository directory
cd /path/to/imessage-query-fastmcp-mcp-server

# List available tools
mcp tools ./imessage-query-server.py

# Test a tool call
mcp call get_chat_transcript ./imessage-query-server.py -p '{"phone_number": "+1234567890"}'

The script will automatically handle dependency installation via uv when first run.

🐛 Troubleshooting

Common Error Messages

"❌ Full Disk Access permission required"

• Follow the macOS Permissions Setup section
• Ensure you've restarted your MCP client after granting permission

"Messages database not found"

• Make sure you've used the Messages app at least once
• Verify iMessage is enabled in Messages preferences

"Invalid phone number"

• Phone numbers are validated using Google's phonenumbers library
• Try using E.164 format (e.g., "+1234567890")
• US numbers without country code will be assumed to be US numbers

Getting Help

If you encounter issues:

1. Check the error message for specific guidance
2. Ensure your MCP client has Full Disk Access permission
3. Verify the Messages app has been used and iMessage is enabled
4. Try testing the server directly with mcptools (see Advanced Usage)