iMessage Query MCP Server

1# iMessage Query MCP Server
2 
3An 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.
4 
5## 📋 System Requirements
6 
7- macOS (required for iMessage database access)
8- Python 3.6+
9 
10## 📦 Dependencies
11 
12Install all required dependencies:
13 
14```bash
15# Using pip
16pip install -r requirements.txt
17```
18 
19### Required Packages
20- **fastmcp**: Framework for building Model Context Protocol servers
21- **imessagedb**: Python library for accessing and querying the macOS Messages database
22- **phonenumbers**: Google's phone number handling library for proper number validation and formatting
23 
24All dependencies are specified in `requirements.txt` for easy installation.
25 
26## 📑 Table of Contents
27- [System Requirements](#-system-requirements)
28- [Dependencies](#-dependencies)
29- [MCP Tools](#%EF%B8%8F-mcp-tools)
30- [Getting Started](#-getting-started)
31- [Installation Options](#-installation-options)
32  - [Claude Desktop](#option-1-install-for-claude-desktop)
33  - [Cline VSCode Plugin](#option-2-install-for-cline-vscode-plugin)
34- [Safety Features](#-safety-features)
35- [Development Documentation](#-development-documentation)
36- [Environment Variables](#%EF%B8%8F-environment-variables)
37 
38## 🛠️ MCP Tools
39 
40The server exposes the following tools to LLMs:
41 
42### get_chat_transcript
43Retrieve message history for a specific phone number with optional date filtering. Includes:
44- Message text and timestamps
45- Attachment information (if any)
46- Proper phone number validation
47- Date range filtering
48 
49## 🚀 Getting Started
50 
51Clone the repository:
52 
53```bash
54git clone https://github.com/hannesrudolph/imessage-query-fastmcp-mcp-server.git
55cd imessage-query-fastmcp-mcp-server
56```
57 
58## 📦 Installation Options
59 
60You can install this MCP server in either Claude Desktop or the Cline VSCode plugin. Choose the option that best suits your needs.
61 
62### Option 1: Install for Claude Desktop
63 
64Install using FastMCP:
65 
66```bash
67fastmcp install imessage-query-server.py --name "iMessage Query"
68```
69 
70### Option 2: Install for Cline VSCode Plugin
71 
72To use this server with the [Cline VSCode plugin](http://cline.bot):
73 
741. In VSCode, click the server icon (☰) in the Cline plugin sidebar
752. Click the "Edit MCP Settings" button (✎)
763. Add the following configuration to the settings file:
77 
78```json
79{
80  "imessage-query": {
81    "command": "uv",
82    "args": [
83      "run",
84      "--with",
85      "fastmcp",
86      "fastmcp",
87      "run",
88      "/path/to/repo/imessage-query-server.py"
89    ]
90  }
91}
92```
93 
94Replace `/path/to/repo` with the full path to where you cloned this repository (e.g., `/Users/username/Projects/imessage-query-fastmcp-mcp-server`)
95 
96## 🔒 Safety Features
97 
98- Read-only access to the iMessage database
99- Phone number validation using the phonenumbers library
100- Safe attachment handling with missing file detection
101- Date range validation
102- Progress output suppression for clean JSON responses
103 
104## 📚 Development Documentation
105 
106The repository includes documentation files for development:
107 
108- `dev_docs/imessagedb-documentation.txt`: Contains comprehensive documentation about the iMessage database structure and the imessagedb library's capabilities.
109 
110This documentation serves as context when developing features and can be used with LLMs to assist in development.
111 
112## ⚙️ Environment Variables
113 
114No environment variables are required as the server automatically locates the iMessage database in the default macOS location.