iMessage 查询 MCP 服务器

一个通过模型上下文协议（MCP）提供安全访问您 iMessage 数据库的 MCP 服务器。该服务器基于 FastMCP 框架和 imessagedb 库构建，使 LLM 能够进行电话号码验证和自动 macOS 权限处理，从而查询和分析 iMessage 聊天记录。

📋 系统要求

macOS（访问 iMessage 数据库所需）
Python 3.12+（用于现代类型提示）
uv（现代 Python 包管理器）
完整磁盘访问权限（您的 MCP 客户端，如 Claude Desktop、Cursor、VS Code 等）

📦 依赖项

安装 uv（必需）

该项目使用 uv 进行快速可靠的 Python 包管理。请先安装它：

# 使用 Homebrew 安装（推荐）
brew install uv

# 或使用官方安装程序
curl -LsSf https://astral.sh/uv/install.sh | sh

Python 依赖项

脚本使用嵌入式元数据自动管理其依赖项。无需单独安装！依赖项包括：

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

当脚本通过 uv 运行时，所有依赖项将自动安装。

🛠️ MCP 工具

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

get_chat_transcript

检索特定电话号码的消息历史记录，并可选按日期筛选。

参数：

phone_number（必需）：任何格式的电话号码（推荐使用 E.164 格式）
start_date（可选）：ISO 格式的开始日期（YYYY-MM-DD）
end_date（可选）：ISO 格式的结束日期（YYYY-MM-DD）

功能：

自动电话号码验证和格式化
消息文本和时间戳
附件信息（带缺失文件检测）
日期范围筛选（如未指定日期，默认为最近 7 天）
发送者识别（is_from_me 标志）

🚀 入门指南

克隆存储库：

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

📦 安装选项

您可以将此 MCP 服务器安装在 Claude Desktop、Cline VSCode 插件或其他任何 MCP 客户端。选择最适合您需求的选项。

选项 1：Claude Desktop

查找您的 Claude Desktop 配置文件：
- 位置：~/Library/Application Support/Claude/claude_desktop_config.json
- 如果不存在，请创建该文件
添加服务器配置：

{
  "mcpServers": {
    "imessage-query": {
      "command": "/full/path/to/imessage-query-server.py"
    }
  }
}

替换路径为您的克隆存储库的完整路径（例如，/Users/username/Projects/imessage-query-fastmcp-mcp-server/imessage-query-server.py）
完全重启 Claude Desktop（Cmd+Q，然后重新启动）

选项 2：Cline VSCode 插件

要使用 Cline VSCode 插件：

在 VSCode 中，点击 Cline 插件侧边栏中的服务器图标（☰）
点击“编辑 MCP 设置”按钮（✎）
在设置文件中添加以下配置：

{
  "imessage-query": {
    "command": "/full/path/to/imessage-query-server.py"
  }
}

替换路径为您的克隆存储库的完整路径

选项 3：其他 MCP 客户端

对于其他 MCP 客户端，使用直接脚本路径作为命令：

/full/path/to/imessage-query-server.py

脚本的 shebang（#!/usr/bin/env -S uv run --script）将自动处理依赖项管理。

注意：此简化配置取代了之前的 FastMCP 安装方法。脚本现在是自包含的，并通过 uv 管理自己的依赖项。

🔐 macOS 权限设置

此服务器需要完整磁盘访问权限来读取 iMessage 数据库。服务器包括智能权限检测，并将引导您完成设置过程。

自动权限检测

首次使用服务器时，它将：

检测您的 MCP 客户端（Claude Desktop、Cursor、VS Code 等）
检查完整磁盘访问权限
自动打开系统偏好设置到正确的设置面板
提供针对您的应用程序的逐步说明

手动权限设置

如果自动检测不起作用，请按照以下步骤操作：

打开系统偏好设置 → 隐私与安全 → 完整磁盘访问
点击锁形图标并输入您的密码以进行更改
点击 '+' 按钮以添加应用程序
导航并选择您的 MCP 客户端：
- Claude Desktop：/Applications/Claude.app
- Cursor：/Applications/Cursor.app
- VS Code：/Applications/Visual Studio Code.app
完全重启您的 MCP 客户端（Cmd+Q，然后重新启动）

常见问题

权限拒绝错误：确保您在授予权限后重启了您的 MCP 客户端
"uv" 而不是应用程序名称：服务器将自动检测您的实际 MCP 客户端并提供正确的说明
数据库未找到：确保您至少使用过一次 Messages 应用程序，并验证 iMessage 已在 Messages 首选项中启用

安全说明

此服务器仅需要读取访问权限来访问您的 iMessage 数据库。它无法修改、删除或发送消息。

🔒 安全功能

对 iMessage 数据库的只读访问（无法修改、删除或发送消息）
使用 Google 的 phonenumbers 库进行电话号码验证，并正确格式化为 E.164
安全附件处理，带缺失文件检测和元数据提取
日期范围验证以防止无效查询
进度输出抑制以在 MCP 协议中提供干净的 JSON 响应
智能权限检测，带自动系统偏好设置导航
MCP 客户端识别，以提供准确的权限指导

📚 开发文档

存储库包含全面的开发文档：

dev_docs/imessagedb-documentation.txt：关于 iMessage 数据库结构和 imessagedb 库功能的完整文档
dev_docs/fastmcp-documentation.txt：FastMCP 框架细节和 MCP 工具开发
dev_docs/mcp-documentation.txt：模型上下文协议规范

这些文档在开发功能时提供上下文，并可用于使用 LLM 协助开发。

⚙️ 环境变量

变量	描述	默认值
`SQLITE_DB_PATH`	自定义的 iMessage 数据库路径	`~/Library/Messages/chat.db`

服务器自动定位 macOS 默认位置的 iMessage 数据库。仅在需要自定义数据库路径时才需要此环境变量。

🔧 高级用法

自定义数据库路径

如果需要使用自定义数据库路径：

export SQLITE_DB_PATH="/path/to/custom/chat.db"

测试服务器

直接使用 mcptools（github.com/f/mcptools）测试服务器：

# 导航到存储库目录
cd /path/to/imessage-query-fastmcp-mcp-server

# 列出可用工具
mcp tools ./imessage-query-server.py

# 测试工具调用
mcp call get_chat_transcript ./imessage-query-server.py -p '{"phone_number": "+1234567890"}'

首次运行时，脚本将通过 uv 自动处理依赖项安装。

🐛 故障排除

常见错误信息

"❌ 需要 Full Disk Access 权限"

按照 macOS 权限设置部分操作
确保在授予权限后重启了您的 MCP 客户端

"Messages 数据库未找到"

确保您至少使用过一次 Messages 应用程序
验证 Messages 首选项中已启用 iMessage

"无效的电话号码"

电话号码使用 Google 的 phonenumbers 库进行验证
尝试使用 E.164 格式（例如，"+1234567890"）
美国号码不带国家代码将被假定为美国号码

获取帮助

如果您遇到问题：

检查错误信息以获取具体指导
确保您的 MCP 客户端具有 Full Disk Access 权限
验证 Messages 应用程序已使用且 iMessage 已启用
尝试使用 mcptools 直接测试服务器（见高级用法）

hannesrudolph/imessage-query-fastmcp-mcp-server

星标增长

证据时间轴