imessage-mcp 是一个 Model Context Protocol（MCP）服务器，用于在 macOS 上读取 iMessage 数据。项目由 wyattjoh 维护，托管于 GitHub，采用 Deno 单仓库（monorepo）结构，包含两个包：@wyattjoh/imessage 和 @wyattjoh/imessage-mcp。
用途： 该工具旨在让 LLM（大语言模型）能够通过 MCP 协议访问本地 iMessage 数据，实现消息搜索、聊天列表获取、联系人查询等功能。它仅提供只读访问，不能发送或修改消息，且只访问本地数据。
主要能力：
- 按文本内容、联系人或日期范围搜索消息
- 获取最近消息
- 列出所有聊天/对话
- 获取所有联系人/句柄
- 从特定聊天中检索消息
- 按姓名搜索 macOS 联系人，并关联 iMessage 句柄 ID
使用方式： 环境要求：macOS（iMessage 仅限 macOS）、Deno 2.x 或更高版本、对 ~/Library/Messages/chat.db 或通过 IMESSAGE_DB_PATH 配置的自定义数据库的读取权限、对 ~/Library/Application Support/AddressBook/ 的读取权限（用于联系人搜索）。
安装与运行：
- 对于 Claude Desktop 应用集成，需在 claude_desktop_config.json 中添加配置。
- 可通过设置 IMESSAGE_DB_PATH 环境变量打开其他位置的只读 SQLite 数据库，例如定期刷新的 chat.db 快照。进程需要对该自定义文件有读取权限。如果 Deno 没有权限读取 IMESSAGE_DB_PATH，或者该变量为空或未设置，库将使用 ~/Library/Messages/chat.db 而不提示环境访问。
- 从源码运行：克隆仓库，安装依赖（deno cache src/index.ts），运行服务器（deno run --allow-read --allow-env --allow-sys --allow-ffi src/index.ts 或使用任务 deno task start）。
可用工具：
- search_messages：搜索消息，支持过滤条件：query（可选，搜索文本）、handle（可选，按电话号码或电子邮件过滤）、startDate（可选，ISO 日期时间字符串，起始日期）、endDate（可选，ISO 日期时间字符串，结束日期）、limit（可选，最大结果数 1-200，默认 100）、offset（可选，分页偏移，默认 0）。
- get_recent_messages：获取最近消息，参数：limit（可选，消息数量 1-100，默认 20）、offset（可选，分页偏移，默认 0）。
- get_chats：列出所有对话，参数：limit（可选，聊天数量 1-200，默认 50）、offset（可选，分页偏移，默认 0）。
- get_handles：获取所有联系人/句柄，参数：limit（可选，句柄数量 1-200，默认 100）、offset（可选，分页偏移，默认 0）。
- get_messages_from_chat：从特定聊天获取消息，参数：chatGuid（必需，聊天 GUID）、limit（可选，消息数量 1-200，默认 50）、offset（可选，分页偏移，默认 0）。
- search_contacts：按姓名搜索 macOS 联系人并获取电话号码，参数：firstName（必需，名字，如 'John'）、lastName（可选，姓氏，如 'Smith'，若省略则搜索所有姓名字段）、limit（可选，最大结果数 1-200，默认 50）、offset（可选，分页偏移，默认 0）。返回包含电话号码和电子邮件地址的联系人信息，可用作 handle 参数。该功能直接搜索 macOS AddressBook 数据库，以提高性能和可靠性。
分页： 所有工具均支持使用 limit 和 offset 参数进行分页，并返回分页元数据。所有分页工具返回的响应格式包含元数据，帮助用户了解总结果数而无需获取全部、判断是否有更多页（hasMore）、计算当前页和总页数、构建分页 UI 组件。
适用场景： 适用于需要在 macOS 上通过 LLM 或 MCP 客户端访问 iMessage 数据的场景，例如构建聊天记录分析、联系人查询、消息检索等应用。
限制：
- 仅支持 macOS 系统。
- 仅提供只读访问，无法发送或修改消息。
- 仅访问本地数据。
- 需要 Deno 2.x 或更高版本。
- 需要相应的文件读取权限。
其他信息： 该项目为 Deno 工作区单仓库，从根目录运行的所有命令会影响所有包。关于各个包的详细文档，请参考仓库中的完整文档。
