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
- System Requirements
- Dependencies
- MCP Tools
- Getting Started
- Installation Options
- 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. 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:
- 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/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.
Metadata
Release files for iflow-mcp_hannesrudolph-imessage-query-fastmcp-mcp-server 0.1.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| iflow_mcp_hannesrudolph_imessage_query_fastmcp_mcp_server-0.1.1.tar.gz | 6.7 kB | Without provenance | Details for iflow_mcp_hannesrudolph_imessage_query_fastmcp_mcp_server-0.1.1.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| iflow_mcp_hannesrudolph_imessage_query_fastmcp_mcp_server-0.1.1-py3-none-any.whl | Python 3 | none | any | Details for iflow_mcp_hannesrudolph_imessage_query_fastmcp_mcp_server-0.1.1-py3-none-any.whl |
Total release size: 19.1 kB
Release files / iflow_mcp_hannesrudolph_imessage_query_fastmcp_mcp_server-0.1.1.tar.gz
| Download URL | iflow_mcp_hannesrudolph_imessage_query_fastmcp_mcp_server-0.1.1.tar.gz |
|---|---|
| Size | 6.7 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
aebd437c0150456bd07ac719acec93c1300a2bf3cd5d33464571d214aad0b46a
|
|
BLAKE2b-256 checksum How to use checksums |
02fe4541322161d56decea0bb9953dc7ec7af47ab32269b20b6818457f13a2f9
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.10.0 {"installer":{"name":"uv","version":"0.10.0","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Debian GNU/Linux","version":"13","id":"trixie","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
|
Release files / iflow_mcp_hannesrudolph_imessage_query_fastmcp_mcp_server-0.1.1-py3-none-any.whl
| Download URL | iflow_mcp_hannesrudolph_imessage_query_fastmcp_mcp_server-0.1.1-py3-none-any.whl |
|---|---|
| Size | 12.3 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
ae9928a1c4ebd652c8b6abdae369c7e4ff0b8c3e903cd8d40ca94e254f079636
|
|
BLAKE2b-256 checksum How to use checksums |
4a482a30bf615f26769c183ec6c32957f3d487494e79ed3f52835f9a048c03c1
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.10.0 {"installer":{"name":"uv","version":"0.10.0","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Debian GNU/Linux","version":"13","id":"trixie","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
|
Security for iflow-mcp_hannesrudolph-imessage-query-fastmcp-mcp-server 0.1.1
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.