This MCP server provides safe access to your macOS iMessage database via the Model Context Protocol framework. Built with the FastMCP toolkit and the imessagedb library, it exposes a get_chat_transcript tool that lets language models retrieve message history for a given phone number, with optional date filtering. The server enforces read-only access to protect your data and performs phone number validation and safe attachment handling to prevent exposing or misreporting files. To use, run the MCP server in your environment using the recommended uv/uvx command, then call the available MCP tools from your LLM or client that supports MCP consumption. The primary tool of interest is get_chat_transcript, which returns messages, timestamps, attachments (when available), and enforces date-range constraints for precise queries.

Prerequisites:

• macOS (required for iMessage database access)
• Python 3.6+ installed on the host
• pip available in PATH
• Access to the macOS iMessage database (the server will locate it automatically)

Installation steps:

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

2. Create and activate a Python environment (optional but recommended): python3 -m venv venv source venv/bin/activate

3. Install dependencies: pip install -r requirements.txt

4. Prepare to run the MCP server:

   • Ensure you have FastMCP installed and available in your Python environment.
   • Confirm you have access to the macOS iMessage database (the server will auto-detect its location).

5. Run the MCP server using the recommended command (example using uv/uvx as in the repository guidance): uv run --with fastmcp fastmcp run /path/to/repo/imessage-query-fastmcp-mcp-server/imessage-query-server.py

   or, if using uvx via Python module invocation, adapt accordingly to your environment

Notes and troubleshooting:

• The server operates in read-only mode to protect your iMessage data.
• Ensure the iMessage database location is accessible by the process running the MCP server; the README notes that no environment variables are required because the server locates the database automatically.
• If you encounter issues with phone number validation, verify that the phonenumbers library is properly installed and up to date.
• Attachments are handled safely with missing-file detection to avoid leaking file paths or crashing on missing resources.
• When integrating with a frontend like Claude Desktop or the Cline VSCode plugin, use the provided configuration example to point the client to the uv-based runner and the path to the server script.
• If you modify the repository path, remember to update the path in the MCP config accordingly.