Messages

🚀 消息搜索工具

這是一款強大的消息搜索工具，可讓你在命令行、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 中的消息數據庫，操作步驟如下：

1. 打開 系統設置 > 隱私與安全 > 全磁盤訪問。
2. 點擊 + 並添加你的終端應用（如Terminal.app、iTerm、Warp等）。
3. 重啟終端。

💻 使用示例

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

搜索選項

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可以使用以下工具：

手動MCP配置

對於Claude Desktop或VS Code，可在MCP配置中添加以下內容：

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

🔧 技術細節

1. 自動索引：首次搜索（或檢測到新消息）時，工具會自動執行以下操作：
   • 讀取蘋果消息SQLite數據庫。
   • 構建SQLite FTS5全文搜索索引。
   • 創建MiniSearch模糊搜索索引。
   • 從地址簿解析聯繫人姓名。
2. 搜索機制：同時查詢兩個索引以獲得最佳結果，具備容錯功能。
3. 存儲方式：索引文件存儲在 ~/.messages/ 目錄下：
   • index.db - SQLite FTS5數據庫
   • fuzzy.json - MiniSearch索引
   • stats.json - 索引統計信息

📄 許可證

本項目採用MIT許可證。