messages

messages

从命令行、作为 Claude Code 插件或 MCP 服务，模糊搜索和浏览 Apple Messages（iMessage/SMS）。

功能

• 模糊搜索，支持在所有消息中容错处理拼写错误
• 浏览最近消息、联系人和对话
• 联系人解析——显示姓名而非电话号码
• 上下文显示——查看每条匹配消息前后的消息
• 按发件人或日期范围筛选
• 自动索引——检测到新消息时自动重建索引
• 多种使用方式——CLI、MCP 服务或 Claude Code 插件

要求

• macOS（读取 Apple Messages 数据库）
• Node.js 22+
• 为终端授予“完全磁盘访问权限”（以读取 ~/Library/Messages/chat.db）

安装

Homebrew

brew install cardmagic/tap/messages

npm

npm install -g @cardmagic/messages

Claude Code 插件（推荐）

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

# Add the marketplace
claude plugin marketplace add cardmagic/ai-marketplace

# Install the plugin
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

# Then add as plugin OR MCP server:
claude plugin marketplace add cardmagic/ai-marketplace
claude plugin install messages@cardmagic
# OR
claude mcp add --transport stdio messages -- messages --mcp

授予完全磁盘访问权限

该工具需要读取你的 Messages 数据库 ~/Library/Messages/chat.db：

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

使用方法

CLI

浏览命令

# Show most recent messages (who texted me?)
messages recent

# List contacts by recent activity
messages contacts --limit 10

# List conversations with message counts
messages conversations

# Show recent messages from someone
messages from "Mom"

# Show full conversation thread
messages thread "John" --after 2024-12-01

搜索命令

# Search for messages (index auto-builds on first search)
messages search "coffee tomorrow"

# Filter by sender
messages search "dinner" --from "Mom"

# Filter by date
messages search "meeting" --after 2024-01-01

# Adjust result count and context
messages search "project" --limit 20 --context 5

# Show index statistics
messages stats

# Force rebuild the index
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"]
    }
  }
}

工作原理

1. 自动索引：首次搜索时（或检测到新消息时），该工具会自动：

   • 读取 Apple Messages SQLite 数据库
   • 构建 SQLite FTS5 全文搜索索引
   • 创建 MiniSearch 模糊搜索索引
   • 从通讯录解析联系人姓名

2. 搜索：查询两个索引，以容错拼写错误并获取最佳结果

3. 存储：索引文件存储在 ~/.messages/ 中：

   • index.db——SQLite FTS5 数据库
   • fuzzy.json——MiniSearch 索引
   • stats.json——索引统计信息

许可证

MIT