Hannesrudolph Imessage Query Fastmcp MCP Server

🚀 iMessage 查詢 MCP 服務器

這是一個藉助 Model Context Protocol (MCP) 實現安全訪問的 iMessage 數據庫服務器。它基於 FastMCP 框架和 imessagedb 庫構建，支持大語言模型 (LLMs) 對 iMessage 對話進行查詢與分析，同時具備準確的電話號碼驗證和附件處理功能。

🚀 快速開始

克隆倉庫：

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

✨ 主要特性

• 基於 Model Context Protocol (MCP) 提供安全訪問。
• 允許大語言模型 (LLMs) 查詢和分析 iMessage 對話。
• 具備正確的電話號碼驗證和附件處理功能。

📦 安裝指南

系統要求

• macOS（必需，用於 iMessage 數據庫訪問）
• Python 3.6+

依賴項

安裝所有所需依賴項：

# 使用 pip
pip install -r requirements.txt

必須的包

• fastmcp：構建 Model Context Protocol 服務器的框架。
• imessagedb：用於訪問和查詢 macOS 消息數據庫的 Python 庫。
• phonenumbers：Google 的電話號碼處理庫，用於正確的號碼驗證和格式化。

所有依賴項均在 requirements.txt 文件中列出，便於安裝。

安裝選項

您可以在 Claude Desktop 或 Cline VSCode 插件中安裝此 MCP 服務器。選擇最適合您的選項。

選項1：Claude Desktop 安裝

使用 FastMCP 安裝：

fastmcp install imessage-query-server.py --name "iMessage 查詢"

選項2：Cline VSCode 插件安裝

要與 Cline VSCode 插件 使用此服務器：

1. 在 VSCode 中，點擊 Cline 插件側邊欄中的服務器圖標 (☰)。
2. 點擊“編輯 MCP 設置”按鈕 (✎)。
3. 將以下配置添加到設置文件中：

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

將 /path/to/repo 替換為您克隆倉庫的實際路徑（例如，/Users/username/Projects/imessage-query-fastmcp-mcp-server）

💻 使用示例

基礎用法

該服務器向 LLM 提供以下工具：

get_chat_transcript

獲取特定電話號碼的聊天曆史記錄，可選日期過濾。包含：

• 消息文本和時間戳
• 附件信息（如有）
• 正確的電話號碼驗證
• 日期範圍過濾

🔧 技術細節

安全功能

• iMessage 數據庫的只讀訪問。
• 使用 phonenumbers 庫進行電話號碼驗證。
• 附件處理的安全性檢測（缺失文件檢測）。
• 日期範圍驗證。
• 進度輸出抑制以保持 JSON 響應乾淨。

📚 詳細文檔

倉庫包含用於開發的文檔：

• dev_docs/imessagedb-documentation.txt：包含有關 iMessage 數據庫結構和 imessagedb 庫功能的全面文檔。

此文檔在開發時作為上下文使用，並可與 LLM 結合使用以協助開發。

⚙️ 環境變量

無需設置環境變量，服務器會自動定位到 macOS 的默認 iMessage 數據庫位置。