](https://mseep.ai/app/hannesrudolph-imessage-query-fastmcp-mcp-server)
iMessage查询MCP服务器
一个MCP服务器，通过模型上下文协议（MCP）提供对iMessage数据库的安全访问。此服务器使用FastMCP框架和imessagedb库构建，使LLM能够通过适当的电话号码验证和自动macOS权限处理来查询和分析iMessage对话。
📋 系统要求
- macOS（访问iMessage数据库所需）
- Python 3.12+（现代类型提示所需）
- 紫外线 （现代Python包管理器）
- 完整磁盘访问权限 适用于您的MCP客户端（Claude Desktop、Cursor、VS Code等）
📦 依赖项
安装uv（必需）
此项目使用 uv 用于快速、可靠的Python包管理。先安装：
# Install uv using Homebrew (recommended)
brew install uv
# Or install using the official installer
curl -LsSf https://astral.sh/uv/install.sh | shPython依赖关系
脚本使用嵌入的元数据自动管理其依赖关系。无需单独安装！依赖关系包括：
- fastmcp：构建模型上下文协议服务器的框架
- 消息：用于访问和查询macOS Messages数据库的Python库
- 电话号码：谷歌的电话号码处理库，用于正确的号码验证和格式化
当脚本通过运行时，所有依赖项都会自动安装 uv.
📑 目录
- 克劳德桌面 - Cline VSCode插件
🛠️ 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📦 安装选项
您可以在Claude Desktop、Cline VSCode插件或任何其他MCP客户端中安装此MCP服务器。选择最适合您需求的选项。
选项1：克劳德桌面
- 查找您的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)
- 重新启动克劳德桌面 完全（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剧本很精彩(#!/usr/bin/env -S uv run --script)自动处理依赖关系管理。
备注：此简化配置取代了以前的FastMCP安装方法。该脚本现在是自包含的，并通过以下方式管理其自身的依赖关系 uv.🔐 macOS权限设置
此服务器需要 全磁盘访问 读取iMessage数据库的权限。服务器包括智能权限检测，并将指导您完成设置过程。
自动权限检测
当您首次使用服务器时，它将：
- 检测您的MCP客户端 （克劳德桌面、光标、VS代码等）
- 检查磁盘是否完全访问 许可
- 自动打开系统首选项 转到正确的设置面板
- 提供分步说明 特定于您的应用程序
手动权限设置
如果自动检测不起作用，请按照以下步骤操作：
- 打开系统首选项 → 隐私和安全 → 全磁盘访问
- 单击锁图标 并输入密码进行更改
- 点击“+”按钮 添加应用程序
- 导航到并选择您的MCP客户端：
- 克劳德桌面: /Applications/Claude.app - 光标: /Applications/Cursor.app - VS代码: /Applications/Visual Studio Code.app
- 重新启动MCP客户端 完全（Cmd+Q，然后重新启动）
常见问题
- 权限被拒绝错误：确保在授予权限后重新启动了MCP客户端
- “uv”而不是应用程序名称：服务器将自动检测您的实际MCP客户端并提供正确的指令
- 找不到数据库：确保您已使用Messages应用程序并且启用了iMessage
安全说明
此服务器只需要 读取访问 到您的iMessage数据库。它不能修改、删除或发送消息。
🔒 安全功能
- 只读访问 到iMessage数据库（无法修改、删除或发送消息）
- 电话号码验证 使用具有正确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 |
服务器会自动将iMessage数据库定位在默认的macOS位置。仅自定义数据库位置需要环境变量。
🔧 高级用法
自定义数据库路径
如果需要使用自定义数据库路径：
export SQLITE_DB_PATH="/path/to/custom/chat.db"测试服务器
直接使用mcptools测试服务器（github.com/f/mcptools）：
# Navigate to the repository directory
cd /path/to/imessage-query-fastmcp-mcp-server
# List available tools
mcp tools ./imessage-query-server.py
# Test a tool call
mcp call get_chat_transcript ./imessage-query-server.py -p '{"phone_number": "+1234567890"}'该脚本将通过以下方式自动处理依赖关系安装 uv 第一次跑步时。
🐛 故障排除
常见错误消息
"❌ 需要完整磁盘访问权限“
- 跟随 macOS权限设置 章节
- 确保在授予权限后重新启动了MCP客户端
“找不到邮件数据库”
- 确保您至少使用过一次Messages应用程序
- 验证在“消息”首选项中启用了iMessage
“电话号码无效”
- 电话号码使用谷歌的电话号码库进行验证
- 尝试使用E.164格式（例如“+1234567890”）
- 没有国家代码的美国号码将被假定为美国号码
获取帮助
如果您遇到问题：
- 查看错误消息以获取具体指导
- 确保您的MCP客户端具有完全磁盘访问权限
- 验证消息应用程序是否已使用，iMessage是否已启用
- 尝试使用mcptools直接测试服务器（请参阅高级用法）