iMessage 查询 MCP 服务器

这是一个通过模型上下文协议（MCP）提供对您的iMessage数据库安全访问的MCP服务器。该服务器基于FastMCP框架和imessagedb库构建，使大型语言模型能够查询和分析iMessage对话，并进行适当的电话号码验证和自动macOS权限处理。

📋 系统需求

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

📦 依赖项

安装uv（必需）

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

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

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

Python 依赖项

脚本会自动管理其依赖项，无需单独安装！依赖项包括：

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

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

📑 目录

• 系统需求
• 依赖项
• MCP工具
• 开始使用
• 安装选项
  • Claude Desktop
  • Cline VSCode插件
• macOS权限设置
• 安全特性
• 开发文档
• 环境变量

🛠️ MCP工具

服务器向大型语言模型暴露以下工具：

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

1. 找到您的Claude Desktop配置文件：

   • 位置：~/Library/Application Support/Claude/claude_desktop_config.json
   • 如果不存在，请创建该文件

2. 添加服务器配置：

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

3. 替换路径为克隆仓库的完整路径（例如：/Users/username/Projects/imessage-query-fastmcp-mcp-server/imessage-query-server.py）

4. 完全重启Claude Desktop（Cmd+Q，然后重新启动）

选项2：Cline VSCode插件

要与Cline VSCode插件一起使用此服务器：

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

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

4. 替换路径为克隆仓库的完整路径

选项3：其他MCP客户端

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

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

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

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

🔐 macOS权限设置

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

自动权限检测

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

1. 检测您的MCP客户端（如Claude Desktop、Cursor、VS Code等）
2. 检查完全磁盘访问权限
3. 自动打开系统偏好设置到正确的设置面板
4. 提供针对您应用程序的具体步骤指导

手动权限设置

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

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

常见问题

• 权限被拒绝错误：确保在授予权限后已完全重启您的MCP客户端
• "uv"而不是应用名称：服务器会自动检测您的实际MCP客户端并提供正确的指导
• 数据库未找到：确保您已经使用过Messages应用且iMessage已启用

安全注意事项

此服务器仅需读取访问您的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：模型上下文协议规范

这些文档在开发功能时提供背景信息，并可用于辅助开发。

⚙️ 环境变量

变量	描述	默认值
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自动处理依赖项安装。

🐛 故障排除

常见错误信息

"❌ 需要完全磁盘访问权限"

• 请参阅macOS权限设置部分
• 确保在授予权限后已完全重启您的MCP客户端

"未找到Messages数据库"

• 确保至少使用过一次Messages应用
• 验证Messages首选项中是否启用了iMessage

"无效电话号码"

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

获取帮助

遇到问题时：

1. 查看错误消息以获取具体指导
2. 确保您的MCP客户端具有完全磁盘访问权限
3. 验证Messages应用已被使用且iMessage已启用
4. 尝试直接使用mcptools测试服务器（参见高级用法）