iMessage Query

by hannesrudolph

69 stars

290 downloads

Not rated

GitHub

About

An MCP server for querying your iMessage database on macOS, allowing LLMs to safely access and search conversations.

Details

Author: hannesrudolph
Repository: hannesrudolph/imessage-query-fastmcp-mcp-server
GitHub stars: 69
Downloads: 290
Categories: Search, Other, Productivity, Knowledge Base, Developer Tools, Design, AI, Community, Database, Communication, Frontend, Security

Setting up with Highlight

This MCP is not yet compatible with Highlight’s one-click setup. However, you can still use it with Highlight by following these steps:

Download and install Highlight from highlightai.com/download
Navigate to the plugins tab and select "Add Custom Plugin"
Configure the plugin with the settings below
Plugin Name iMessage Query

Command (node, npx, python, etc.) uv
Arguments
- Argument 1 run
- Argument 2 --with
- Argument 3 fastmcp
- Argument 4 fastmcp
- Argument 5 run
- Argument 6 /path/to/repo/imessage-query-server.py
Please refer to the README for specific instructions on how to obtain API keys or other required environment variables.
Enable "Start Automatically" if you want the plugin to start when Highlight launches

Setting up with Cursor

Open Cursor's settings
Navigate to the MCP section
Click "Add new Global MCP server"
Copy and paste the configuration below based on your operating system

JSON

{
    "mcpServers": {
        "imessage query": {
            "cwd": null,
            "env": {},
            "args": [
                "run",
                "--with",
                "fastmcp",
                "fastmcp",
                "run",
                "/path/to/repo/imessage-query-server.py"
            ],
            "shell": false,
            "command": "uv"
        }
    }
}

JSON

{
    "mcpServers": {
        "imessage query": {
            "cwd": null,
            "env": {},
            "args": [
                "run",
                "--with",
                "fastmcp",
                "fastmcp",
                "run",
                "/path/to/repo/imessage-query-server.py"
            ],
            "shell": false,
            "command": "uv"
        }
    }
}

JSON

{
    "mcpServers": {
        "imessage query": {
            "cwd": null,
            "env": {},
            "args": [
                "run",
                "--with",
                "fastmcp",
                "fastmcp",
                "run",
                "/path/to/repo/imessage-query-server.py"
            ],
            "shell": false,
            "command": "uv"
        }
    }
}

Setting up with Claude Desktop

Open Claude Desktop's settings
Go to the Integrations tab
Click "Add MCP Server"
Use the configuration below based on your operating system

Note: Make sure Claude Desktop is running before attempting to connect.

JSON

{
    "mcpServers": {
        "imessage query": {
            "cwd": null,
            "env": {},
            "args": [
                "run",
                "--with",
                "fastmcp",
                "fastmcp",
                "run",
                "/path/to/repo/imessage-query-server.py"
            ],
            "shell": false,
            "command": "uv"
        }
    }
}

JSON

{
    "mcpServers": {
        "imessage query": {
            "cwd": null,
            "env": {},
            "args": [
                "run",
                "--with",
                "fastmcp",
                "fastmcp",
                "run",
                "/path/to/repo/imessage-query-server.py"
            ],
            "shell": false,
            "command": "uv"
        }
    }
}

JSON

{
    "mcpServers": {
        "imessage query": {
            "cwd": null,
            "env": {},
            "args": [
                "run",
                "--with",
                "fastmcp",
                "fastmcp",
                "run",
                "/path/to/repo/imessage-query-server.py"
            ],
            "shell": false,
            "command": "uv"
        }
    }
}

Setting up with Windsurf

Open Windsurf's preferences
Go to the Integrations section
Click "Add MCP Integration"
Use the configuration below based on your operating system

JSON

{
    "mcpServers": {
        "imessage query": {
            "cwd": null,
            "env": {},
            "args": [
                "run",
                "--with",
                "fastmcp",
                "fastmcp",
                "run",
                "/path/to/repo/imessage-query-server.py"
            ],
            "shell": false,
            "command": "uv"
        }
    }
}

JSON

{
    "mcpServers": {
        "imessage query": {
            "cwd": null,
            "env": {},
            "args": [
                "run",
                "--with",
                "fastmcp",
                "fastmcp",
                "run",
                "/path/to/repo/imessage-query-server.py"
            ],
            "shell": false,
            "command": "uv"
        }
    }
}

JSON

{
    "mcpServers": {
        "imessage query": {
            "cwd": null,
            "env": {},
            "args": [
                "run",
                "--with",
                "fastmcp",
                "fastmcp",
                "run",
                "/path/to/repo/imessage-query-server.py"
            ],
            "shell": false,
            "command": "uv"
        }
    }
}

Setting up with Cline

Open Cline's settings
Navigate to the Integrations section
Click "Add MCP Server"
Copy and paste the configuration below based on your operating system

Note: Make sure to restart Cline after adding the configuration.

JSON

{
    "mcpServers": {
        "imessage query": {
            "cwd": null,
            "env": {},
            "args": [
                "run",
                "--with",
                "fastmcp",
                "fastmcp",
                "run",
                "/path/to/repo/imessage-query-server.py"
            ],
            "shell": false,
            "command": "uv"
        }
    }
}

JSON

{
    "mcpServers": {
        "imessage query": {
            "cwd": null,
            "env": {},
            "args": [
                "run",
                "--with",
                "fastmcp",
                "fastmcp",
                "run",
                "/path/to/repo/imessage-query-server.py"
            ],
            "shell": false,
            "command": "uv"
        }
    }
}

JSON

{
    "mcpServers": {
        "imessage query": {
            "cwd": null,
            "env": {},
            "args": [
                "run",
                "--with",
                "fastmcp",
                "fastmcp",
                "run",
                "/path/to/repo/imessage-query-server.py"
            ],
            "shell": false,
            "command": "uv"
        }
    }
}

Setting up with Goose

Open Goose's preferences
Go to the Integrations tab
Select "MCP Servers"
Click "Add New Server"
Use the configuration below based on your operating system

JSON

{
    "mcpServers": {
        "imessage query": {
            "cwd": null,
            "env": {},
            "args": [
                "run",
                "--with",
                "fastmcp",
                "fastmcp",
                "run",
                "/path/to/repo/imessage-query-server.py"
            ],
            "shell": false,
            "command": "uv"
        }
    }
}

JSON

{
    "mcpServers": {
        "imessage query": {
            "cwd": null,
            "env": {},
            "args": [
                "run",
                "--with",
                "fastmcp",
                "fastmcp",
                "run",
                "/path/to/repo/imessage-query-server.py"
            ],
            "shell": false,
            "command": "uv"
        }
    }
}

JSON

{
    "mcpServers": {
        "imessage query": {
            "cwd": null,
            "env": {},
            "args": [
                "run",
                "--with",
                "fastmcp",
                "fastmcp",
                "run",
                "/path/to/repo/imessage-query-server.py"
            ],
            "shell": false,
            "command": "uv"
        }
    }
}

From the repository

Clone the repository:

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

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

Install using FastMCP:

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

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)

No environment variables are required as the server automatically locates the iMessage database in the default macOS location.29:["$","div",null,{"className":"m

`get_chat_transcript`

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

Claude Desktop / Cursor

Paste into your MCP client config file to install this server.

{
    "mcpServers": {
        "imessage query": {
            "cwd": null,
            "env": {},
            "args": [
                "run",
                "--with",
                "fastmcp",
                "fastmcp",
                "run",
                "/path/to/repo/imessage-query-server.py"
            ],
            "shell": false,
            "command": "uv"
        }
    }
}

Linux

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

Macos

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

Windows

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

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.

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

# Using pip pip install -r requirements.txt

- 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 inrequirements.txtfor easy installation.

- System Requirements
- Dependencies
- MCP Tools
- Getting Started
- Installation Options

- Claude Desktop
- Cline VSCode Plugin

The server exposes the following tools to LLMs:

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

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

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

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:
- In VSCode, click the server icon (☰) in the Cline plugin sidebar
- Click the "Edit MCP Settings" button (✎)
- 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/repowith the full path to where you cloned this repository (e.g.,/Users/username/Projects/imessage-query-fastmcp-mcp-server)

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.

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

Search global news using natural language. Webz.io News Search API returns the most relevant articles and content, with filters for source, country, language, date, sentiment, and category.

Fetch, convert, and search AWS documentation pages, with recommendations for related content.

Search campgrounds around the world on campertunity, check availability, and provide booking links.

The Ferryhopper MCP Server exposes ferry routes, schedules and booking redirects so an AI assistant can discover connections across Europe and the Mediterranean and send users to Ferryhopper to complete bookings.

All-in-One SEO & Web Intelligence Toolkit API from FetchSERP.

MCP server that provides read-only access to HyperKitty, the web-based email archive component of Mailman 3.

At Sunrise Apps, we believe AI agents should be limitless, especially when it comes to visual data. We created ImageSorcery to bridge the critical gap in AI's ability to interact with and manipulate images directly, all while upholding the highest standards of privacy and security.

Just Domain is the domain registrar for businesses built with AI. Its remote MCP server checks availability and returns first-year and renewal pricing, plus a link to register on justdomain.ai, with DNS and WHOIS privacy in the same place. No account, no API key, read only. Endpoint: https://mcp.justdomain.ai/

Research tools, including a Sqlite-backed document stash

Semantic search over 9 free-license stock photo sources. Hosted remote server with OAuth — no API key to paste.

SerpApi MCP Server for Google and other search engine results

No reviews yet — be the first

Use Google, GitHub, or an email account so ratings stay tied to real people.

Email sign in

No reviews posted yet.

About

Details

Jump to

Setting up with Highlight

From the repository

get_chat_transcript

Claude Desktop / Cursor

Linux

Macos

Windows

Option 2: Install for Cline VSCode Plugin

Install

More like this

Sequential Thinking

Time

Brave Search

Filesystem

EverArt

Google Drive

`get_chat_transcript`