iMessage Query MCP Server

iMessage Query MCP 服务

一个通过模型上下文协议（MCP）安全访问 iMessage 数据库的 MCP 服务。此服务使用 FastMCP 框架和 imessagedb 库构建，支持大模型查询和分析 iMessage 对话，并提供电话号码验证和附件处理功能。

📋 系统要求

• macOS（访问 iMessage 数据库所必需）
• Python 3.6+

📦 依赖项

安装所有必需的依赖项：

# Using pip
pip install -r requirements.txt

必需的软件包

• fastmcp：用于构建模型上下文协议服务的框架
• imessagedb：用于访问和查询 macOS 信息数据库的 Python 库
• phonenumbers：Google 的电话号码处理库，可用于正确验证和格式化号码

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

📑 目录

• 系统要求
• 依赖项
• MCP 工具
• 开始使用
• 安装选项
  • Claude Desktop
  • Cline VSCode 插件
• 安全功能
• 开发文档
• 环境变量

🛠️ MCP 工具

该服务向大模型提供以下工具：

get_chat_transcript

获取指定电话号码的消息历史记录，可选择按日期筛选。包括：

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

🚀 开始使用

克隆此仓库：

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

📦 安装选项

你可以将此 MCP 服务安装到 Claude Desktop 或 Cline VSCode 插件中。选择最适合你需求的选项。

选项 1：安装到 Claude Desktop

使用 FastMCP 安装：

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

选项 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 库功能的全面文档。

开发功能时，可将此文档作为上下文；也可配合大模型辅助开发。

⚙️ 环境变量

无需设置环境变量，因为服务会自动在 macOS 默认位置查找 iMessage 数据库。