MCPgee
MCPgee
MCPgeeMCPgee

iMessage Query

v1.0.0•Search & Data Extraction•stable

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

llmmcpmcp-server
Share:
77
Stars
0
Downloads
0
Weekly
0/5
View on GitHub

What is iMessage Query?

iMessage Query is a Model Context Protocol (MCP) server that allows AI assistants like Claude, Cursor, and VS Code to 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 ...

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

This server falls under the Search & Data Extraction category on MCPgee, the world's largest MCP server directory with 33,000+ servers.

Features

  • An MCP server that provides safe access to your iMessage dat

Use Cases

iMessage database access and analysis
Conversation history search
Secure message querying
hannesrudolph

Maintainer

LicenseMIT
Languagepython
Versionv1.0.0
UpdatedMar 31, 2026
Statushealthy
Maintenanceactive

Works with

ClaudeOpenAIwindowsmacoslinux
View SourceBrowse All Servers

Installation

Manual Installation

npx imessage-query-fastmcp

Configuration

Configuration Details

Config File

claude_desktop_config.json

Performance

Response Metrics

Response Time< 200ms
ThroughputMedium

Resource Usage

Memory UsageLow
CPU UsageLow

How to Set Up and Use iMessage Query

iMessage Query MCP Server is a macOS-only Python server built with the FastMCP framework that provides safe, read-only access to your local iMessage database (~/.imessagedb or the default macOS Messages store). It allows LLMs like Claude to retrieve conversation transcripts for specific contacts, filter messages by date range, and inspect attachment metadata — all with proper phone number validation via Google's phonenumbers library. Because the access is strictly read-only and the server runs locally, your message data never leaves your machine, making it suitable for tasks like summarizing past conversations, searching for information shared over iMessage, or analyzing communication patterns.

Prerequisites

  • macOS (required — iMessage database is only present on macOS)
  • Python 3.6 or later
  • Full Disk Access granted to your terminal or MCP client in System Preferences so the process can read ~/Library/Messages/chat.db
  • An MCP-compatible client such as Claude Desktop
  • The repository cloned locally (no PyPI package — install via FastMCP from source)
1

Grant Full Disk Access to your terminal

On macOS, go to System Settings > Privacy & Security > Full Disk Access and add your terminal application (Terminal.app or iTerm2) and, if using Claude Desktop, the Claude Desktop app itself. Without this, the process cannot read chat.db.

2

Clone the repository

Clone the imessage-query-fastmcp-mcp-server repository to your local machine.

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

Install Python dependencies

Install the required packages: fastmcp (the MCP framework), imessagedb (iMessage database reader), and phonenumbers (phone number validation).

pip install -r requirements.txt
4

Install the server into Claude Desktop

Use the fastmcp CLI to register the server with Claude Desktop under the name 'iMessage Query'. FastMCP handles the MCP configuration automatically.

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

Alternative: configure manually for Cline or other clients

If you are using the Cline VSCode plugin or another MCP client, add the server configuration manually. Replace /path/to/repo with the absolute path to the cloned repository.

{
  "imessage-query": {
    "command": "uv",
    "args": [
      "run",
      "--with",
      "fastmcp",
      "fastmcp",
      "run",
      "/path/to/imessage-query-fastmcp-mcp-server/imessage-query-server.py"
    ]
  }
}
6

Restart Claude Desktop and test

Restart Claude Desktop. The iMessage Query tool (get_chat_transcript) should appear in the tool list. Test by asking Claude to retrieve messages from a specific phone number.

iMessage Query Examples

Client configuration

Manual MCP configuration using uv to run the server from the cloned repository path.

{
  "mcpServers": {
    "imessage-query": {
      "command": "uv",
      "args": [
        "run",
        "--with",
        "fastmcp",
        "fastmcp",
        "run",
        "/Users/you/imessage-query-fastmcp-mcp-server/imessage-query-server.py"
      ]
    }
  }
}

Prompts to try

Example prompts to retrieve and analyze iMessage conversations using the get_chat_transcript tool.

- "Get the last 30 days of iMessages with +1 415 555 0100 and summarize the key topics"
- "Retrieve all messages from my conversation with +44 20 7946 0958 between January 1 and March 31"
- "Search my iMessages with +1 650 555 0199 for any messages that mention a meeting link or Zoom URL"
- "How many messages did I exchange with +1 212 555 0147 last month?"

Troubleshooting iMessage Query

Permission denied or empty results when accessing chat.db

macOS protects ~/Library/Messages/chat.db with Full Disk Access. Go to System Settings > Privacy & Security > Full Disk Access and add both your terminal app and Claude Desktop. You may need to restart both after granting access.

Phone number validation fails — get_chat_transcript returns no messages

The server validates phone numbers using the phonenumbers library. Pass numbers in E.164 international format (e.g. +14155550100). Omitting the country code or using local formats may cause validation to reject the number.

fastmcp install command not found

Install FastMCP globally with 'pip install fastmcp', then re-run the install command. If you use a virtual environment, activate it first or use 'python -m fastmcp install' instead.

Frequently Asked Questions about iMessage Query

What is iMessage Query?

iMessage Query is a Model Context Protocol (MCP) server that 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 It connects AI assistants to external tools and data sources through a standardized interface.

How do I install iMessage Query?

Follow the installation instructions on the iMessage Query GitHub repository. Clone the repo, install dependencies, and add the server config to your AI client.

Which AI clients work with iMessage Query?

iMessage Query works with all major MCP-compatible AI clients including Claude Desktop, Claude Code, Cursor, VS Code (GitHub Copilot), Windsurf, and Cline.

Is iMessage Query free to use?

Yes, iMessage Query is open source and available under the MIT license. You can use it freely in both personal and commercial projects.

Learn More About MCP Servers

Getting Started with MCP

Set up your first MCP server in minutes

MCP Setup Guide

Configure MCP in Claude, Cursor & VS Code

All MCP Tutorials

18+ hands-on guides for developers

MCP FAQ

40+ answers about Model Context Protocol

iMessage Query Alternatives — Similar Search & Data Extraction Servers

Looking for alternatives to iMessage Query? Here are other popular search & data extraction servers you can use with Claude, Cursor, and VS Code.

TrendRadar

★ 58.0k

A real-time hotspot monitoring and news aggregation assistant that provides AI-powered analysis of trending topics across multiple platforms via the Model Context Protocol. It enables users to track news and receive automated notifications through va

Scrapling

★ 52.7k

🕷️ An adaptive Web Scraping framework that handles everything from a single request to a full-scale crawl!

PDF Math Translate

★ 33.9k

[EMNLP 2025 Demo] PDF scientific paper translation with preserved formats - 基于 AI 完整保留排版的 PDF 文档全文双语翻译，支持 Google/DeepL/Ollama/OpenAI 等服务，提供 CLI/GUI/MCP/Docker/Zotero

GPT Researcher

★ 27.2k

An autonomous agent that conducts deep research on any data using any LLM providers

Agent Reach

★ 20.1k

Give your AI agent eyes to see the entire internet. Read & search Twitter, Reddit, YouTube, GitHub, Bilibili, XiaoHongShu — one CLI, zero API fees.

Xiaohongshu

★ 13.7k

MCP for xiaohongshu.com

Browse More Search & Data Extraction MCP Servers

Explore all search & data extraction servers available in the MCPgee directory. Each server includes setup guides for Claude, Cursor, and VS Code.

Search & Data ExtractionBrowse All Servers

Quick Config Preview

{ "mcpServers": { "imessage-query-fastmcp": { "command": "npx", "args": ["-y", "imessage-query-fastmcp"] } } }

Add this to your claude_desktop_config.json or .cursor/mcp.json

Read the full setup guide →

Ready to use iMessage Query?

Browse our complete directory of 33,000+ MCP servers, read setup guides for your editor, and start building with the Model Context Protocol.

33,000+ ServersFree & Open SourceStep-by-Step Guides
Explore All ServersRead Our Guides