金大哥 - messages MCP 详情

article

README

🚀 消息搜索工具

这是一款强大的消息搜索工具，可让你在命令行、Claude Code插件或MCP服务器中对苹果消息（iMessage/SMS）进行模糊搜索和浏览，极大提升信息查找效率。

🚀 快速开始

本工具支持在命令行、Claude Code插件或MCP服务器中使用，使用前请确保满足以下要求：

macOS系统（从苹果消息数据库读取数据）
Node.js 22+
终端需具备全磁盘访问权限（用于读取 ~/Library/Messages/chat.db）

✨ 主要特性

模糊搜索：具备容错功能，可在所有消息中进行模糊查找。
近期消息浏览：能够浏览近期消息、联系人及对话。
联系人解析：显示联系人姓名而非电话号码。
上下文显示：查看匹配消息的前后文。
筛选功能：可按发件人或日期范围进行筛选。
自动索引：检测到新消息时自动重建索引。
多接口支持：提供CLI、MCP服务器和Claude Code插件等多种使用方式。

📦 安装指南

使用Homebrew安装

brew install cardmagic/tap/messages

使用npm安装

npm install -g @cardmagic/messages

安装Claude Code插件（推荐）

安装为插件可获得技能（自动调用）和斜杠命令：

# 添加市场
claude plugin marketplace add cardmagic/ai-marketplace

# 安装插件
claude plugin install messages@cardmagic

安装后可获得以下功能：

技能：当你询问短信/iMessage相关问题时，Claude会自动搜索消息。
斜杠命令：/messages:search、/messages:recent、/messages:from 等。

安装MCP服务器

若不使用插件，可直接访问MCP工具：

claude mcp add --transport stdio messages -- npx -y @cardmagic/messages --mcp

或者先全局安装：

npm install -g @cardmagic/messages
claude mcp add --transport stdio messages -- messages --mcp

从源码安装

git clone https://github.com/cardmagic/messages.git
cd messages
make install

# 然后作为插件或MCP服务器添加：
claude plugin marketplace add cardmagic/ai-marketplace
claude plugin install messages@cardmagic
# 或者
claude mcp add --transport stdio messages -- messages --mcp

授予全磁盘访问权限

该工具需要读取 ~/Library/Messages/chat.db 中的消息数据库，操作步骤如下：

打开 系统设置 > 隐私与安全 > 全磁盘访问。
点击 + 并添加你的终端应用（如Terminal.app、iTerm、Warp等）。
重启终端。

💻 使用示例

CLI使用

浏览命令

# 显示最近的消息（谁给我发了短信？）
messages recent

# 按最近活动列出联系人
messages contacts --limit 10

# 列出带有消息数量的对话
messages conversations

# 显示某人最近的消息
messages from "Mom"

# 显示完整的对话线程
messages thread "John" --after 2024-12-01

搜索命令

# 搜索消息（首次搜索时自动构建索引）
messages search "coffee tomorrow"

# 按发件人筛选
messages search "dinner" --from "Mom"

# 按日期筛选
messages search "meeting" --after 2024-01-01

# 调整结果数量和上下文
messages search "project" --limit 20 --context 5

# 显示索引统计信息
messages stats

# 强制重建索引
messages index

搜索选项

| 选项 | 描述 | |------|------| | -f, --from <sender> | 按发件人姓名或电话号码筛选 | | -a, --after <date> | 仅显示指定日期（YYYY-MM-DD）之后的消息 | | -l, --limit <n> | 最大结果数（默认：10） | | -c, --context <n> | 前后消息数量（默认：2） |

Claude Code插件使用

安装为插件后，你将获得以下功能：

技能（自动调用）：当你询问类似以下问题时，Claude会自动搜索消息：
- "妈妈关于晚餐说了什么？"
- "谁最近给我发了短信？"
- "查找关于旅行的消息"
斜杠命令： | 命令 | 描述 | |------|------| | /messages:search <query> | 带可选筛选的模糊搜索 | | /messages:recent | 显示最近的消息 | | /messages:contacts | 按活动列出联系人 | | /messages:conversations | 列出带有消息数量的对话 | | /messages:from "Name" | 特定人员的消息 | | /messages:thread "Name" | 完整的对话线程 | | /messages:browse <cmd> | 浏览命令的别名 |

MCP服务器使用

安装为MCP服务器后，Claude Code可以使用以下工具： | 工具 | 描述 | |------|------| | search_messages | 模糊匹配搜索消息 | | recent_messages | 获取最近的消息 | | list_contacts | 按活动列出联系人 | | list_conversations | 列出带有数量的对话 | | get_thread | 获取与联系人的对话线程 | | get_message_stats | 获取索引统计信息 |

手动MCP配置

对于Claude Desktop或VS Code，可在MCP配置中添加以下内容：

{
  "mcpServers": {
    "messages": {
      "command": "npx",
      "args": ["-y", "@cardmagic/messages", "--mcp"]
    }
  }
}

🔧 技术细节

自动索引：首次搜索（或检测到新消息）时，工具会自动执行以下操作：
- 读取苹果消息SQLite数据库。
- 构建SQLite FTS5全文搜索索引。
- 创建MiniSearch模糊搜索索引。
- 从地址簿解析联系人姓名。
搜索机制：同时查询两个索引以获得最佳结果，具备容错功能。
存储方式：索引文件存储在 ~/.messages/ 目录下：
- index.db - SQLite FTS5数据库
- fuzzy.json - MiniSearch索引
- stats.json - 索引统计信息

📄 许可证

本项目采用MIT许可证。

messages