iMessage Query MCP Server: Safe Access to Your iMessage Database via Model Context Protocol (MCP)

Overview: What is iMessage Query MCP Server?

The iMessage Query MCP Server provides safe, standardized access to your macOS iMessage database through the Model Context Protocol (MCP). This server leverages FastMCP and imessagedb libraries, enabling LLMs like Claude Desktop, Continue, Cursor, and others to query and analyze your messaging data securely. By integrating this server, AI applications can gain read-only access to rich conversation histories, manage phone number validation, and handle attachments with precision.

🔧 Core Features & MCP Capabilities

The iMessage Query MCP Server offers a comprehensive suite of features that enhance the capabilities of AI applications through MCP. Key functionalities include:

• Read-Only Access: The server ensures read-only access to your iMessage database, preventing any modifications or risks.
• Phone Number Validation: Utilizing Google's phonenumbers library, the server validates and formats phone numbers accurately.
• Attachment Handling: Safe attachment handling is implemented with missing file detection mechanisms to ensure reliability.
• Date Range Filtering: Users can filter messages based on date ranges, providing fine-grained control over data retrieval.

These features are integral to MCP-capable AI applications, facilitating seamless integration and robust data utilization. The server acts as a bridge between the complex iMessage database structure and the simplified API provided by MCP.

⚙️ MCP Architecture & Protocol Implementation

The architecture of the iMessage Query MCP Server is designed around the FastMCP framework for efficient protocol handling. The core component, imessage-query-server.py, serves as the entry point for all client connections, adhering to the strict read-only restrictions outlined by macOS.

Protocol Flow Diagram

graph TB
    A[AI Application] -->|MCP Client| B[MCP Protocol]
    B --> C[MCP Server]
    C --> D[Data Source/Tool]
    style A fill:#e1f5fe
    style C fill:#f3e5f5
    style D fill:#e8f5e8

In this protocol flow, an AI application interacts with the MCP client to request access to specific data. The protocol ensures secure and efficient data transfer between the server and its clients.

Data Architecture Design

graph LR;
    A[AI Application] ---> B[MCP Client]
    B -- Request message --> C[MCP Server]
    C [MCP Server Response]
    C --> D[Data Source/Tool]
    D ---> E[Filtered/Processed Data]
    E ---> F[AIA Query Output]

This design ensures that the data flow is seamless and secure, with MCP servers handling the complex backend logic required for accessing and filtering data.

🚀 Getting Started with Installation

To set up the iMessage Query MCP Server, follow these steps:

1. Clone the Repository:

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

2. Install Dependencies:

   pip install -r requirements.txt
   

3. Run the Server:

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

or for Cline VSCode plugin integration:

4. Edit MCP Settings in Cline Plugin:

   1. In VSCode, click the server icon (☰) in the Cline plugin sidebar.
   2. Click "Edit MCP Settings" (✎).
   3. Add the following configuration to your 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.

💡 Key Use Cases in AI Workflows

Use Case 1: Sentiment Analysis for Customer Service

A large customer service platform uses the iMessage Query MCP Server to retrieve historical conversations between support representatives and customers. By analyzing these interactions using an LLM, they can identify common issues, measure sentiment accurately, and improve their response strategies.

import requests

def get_chat_transcript(phone_number, start_date=None, end_date=None):
    api_url = "http://localhost:8000/chat_transcript"
    params = {"phone_number": phone_number}
    
    if start_date:
        params["start_date"] = start_date
    if end_date:
        params["end_date"] = end_date
    
    response = requests.get(api_url, params=params)
    return response.json()

Use Case 2: Analyzing Patterns in Group Chats

A data analyst leverages the server to query large group conversations for specific patterns or keywords. This helps in understanding user behavior and tailoring marketing strategies.

query = "data analysis"
start_date = "2023-10-05"
end_date = "2023-10-10"

response = get_chat_transcript("1234567890", start_date, end_date)
print(response.json())

🔌 Integration with MCP Clients

The iMessage Query MCP Server is compatible with several MCP clients:

MCP Client	Resources	Tools	Prompts	Status
Claude Desktop	✅	✅	✅	Full Support
Continue	✅	✅	✅	Full Support
Cursor	❌	✅	❌	Tools Only

The compatibility matrix indicates that full support is provided for Claude Desktop and Continue, while Cursor lacks prompt functionality.

📊 Performance & Compatibility Matrix

This MCP server ensures optimal performance with minimal overhead. It operates efficiently by leveraging optimized data retrieval mechanisms from the imessagedb library.

Configuration Sample

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

🛠️ Advanced Configuration & Security

Ensure the iMessage Query MCP Server is thoroughly secured by configuring environment variables and securing API access keys. No specific environment variables are currently required, but you can configure additional security measures as needed.

❓ Frequently Asked Questions (FAQ)

1. Can I use this server with Cursor?
   • Yes, the server supports Cursor for tool integration only.
2. Is data stored securely on the server side?
   • The server operates in read-only mode and stores no data locally, ensuring security.
3. How do I validate incoming phone numbers?
   • The server uses the phonenumbers library to validate and format phone numbers before queries are executed.
4. Can this server handle large volumes of data?
   • Yes, it is designed to handle moderate data loads efficiently using optimized querying techniques.
5. What happens if an attachment is missing from the iMessage database?
   • The server detects missing files and returns appropriate error codes or messages.

👨‍💻 Development & Contribution Guidelines

Contributions are welcome! Developers interested in contributing should review the dev_docs/imessagedb-documentation.txt file for detailed documentation on the imessagedb library's capabilities. Issues can be reported, and pull requests are encouraged to improve functionality and performance.

🌐 MCP Ecosystem & Resources

For further information and support within the broader MCP ecosystem, refer to the Model Context Protocol documentation or reach out to the community forums for additional resources.

By providing a robust and secure gateway into your iMessage database, the iMessage Query MCP Server empowers AI applications to extract valuable insights without compromising user privacy.