iMessage 查询 MCP 服务器

一个通过 Model Context Protocol (MCP) 提供安全访问的 iMessage 数据库服务器。该服务器使用 FastMCP 框架和 imessagedb 库构建，允许大语言模型 (LLMs) 查询和分析 iMessage 对话，并具备正确的电话号码验证和附件处理功能。

📋 系统要求

• macOS（必需，用于 iMessage 数据库访问）
• Python 3.6+

📦 依赖项

安装所有所需依赖项：

# 使用 pip
pip install -r requirements.txt

必须的包

• fastmcp：构建 Model Context Protocol 服务器的框架
• imessagedb：用于访问和查询 macOS 消息数据库的 Python 库
• phonenumbers：Google 的电话号码处理库，用于正确的号码验证和格式化

所有依赖项均在 requirements.txt 文件中列出，便于安装。

📑 目录

• 系统要求
• 依赖项
• MCP 工具
• 快速入门
• 安装选项
  • [Claude Desktop](#选项1-claude-desktop 安装)
  • [Cline VSCode 插件](#选项2-cline-vscode-plugin 安装)
• 安全功能
• 开发文档
• 环境变量

🛠️ MCP 工具

该服务器向 LLM 提供以下工具：

get_chat_transcript

获取特定电话号码的聊天历史记录，可选日期过滤。包含：

• 消息文本和时间戳
• 附件信息（如有）
• 正确的电话号码验证
• 日期范围过滤

🚀 快速入门

克隆仓库：

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

📦 安装选项

您可以在 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）

🔒 安全功能

• iMessage 数据库的只读访问
• 使用 phonenumbers 库进行电话号码验证
• 附件处理的安全性检测（缺失文件检测）
• 日期范围验证
• 进度输出抑制以保持 JSON 响应干净

📚 开发文档

仓库包含用于开发的文档：

• dev_docs/imessagedb-documentation.txt：包含有关 iMessage 数据库结构和 imessagedb 库功能的全面文档。

此文档在开发时作为上下文使用，并可与 LLM 结合使用以协助开发。

⚙️ 环境变量

无需设置环境变量，服务器会自动定位到 macOS 的默认 iMessage 数据库位置。