Fuzzy search and browse Apple Messages/iMessage from CLI or MCP server
npm install @cardmagic/messagesFuzzy search and browse Apple Messages (iMessage/SMS) from the command line, as a Claude Code plugin, or as an MCP server.
- Fuzzy search with typo tolerance across all your messages
- Browse recent messages, contacts, and conversations
- Contact resolution - shows names instead of phone numbers
- Context display - see messages before/after each match
- Filter by sender or date range
- Auto-indexing - index automatically rebuilds when new messages are detected
- Multiple interfaces - CLI, MCP server, or Claude Code plugin
- macOS (reads from Apple Messages database)
- Node.js 22+
- Full Disk Access permission for your terminal (to read ~/Library/Messages/chat.db)
Install as a plugin to get skills (auto-invoked) and slash commands:
``bashAdd the marketplace
claude plugin marketplace add cardmagic/messages
This gives you:
- Skill: Claude automatically searches messages when you ask about texts/iMessages
- Slash commands:
/messages:search, /messages:recent, /messages:from, and more$3
For direct MCP tool access without the plugin:
`bash
claude mcp add --transport stdio messages -- npx -y @cardmagic/messages --mcp
`Or install globally first:
`bash
npm install -g @cardmagic/messages
claude mcp add --transport stdio messages -- messages --mcp
`$3
`bash
git clone https://github.com/cardmagic/messages.git
cd messages
make installThen add as plugin OR MCP server:
claude plugin marketplace add cardmagic/messages
claude plugin install messages@cardmagic
OR
claude mcp add --transport stdio messages -- messages --mcp
`Granting Full Disk Access
The tool needs to read your Messages database at
~/Library/Messages/chat.db:1. Open System Settings > Privacy & Security > Full Disk Access
2. Click + and add your terminal app (Terminal.app, iTerm, Warp, etc.)
3. Restart your terminal
Usage
$3
#### Browse Commands
`bash
Show most recent messages (who texted me?)
messages recentList contacts by recent activity
messages contacts --limit 10List conversations with message counts
messages conversationsShow recent messages from someone
messages from "Mom"Show full conversation thread
messages thread "John" --after 2024-12-01
`#### Search Commands
`bash
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-01Adjust result count and context
messages search "project" --limit 20 --context 5Show index statistics
messages statsForce rebuild the index
messages index
`#### Search Options
| Option | Description |
|--------|-------------|
|
-f, --from | Filter by sender name or phone |
| -a, --after | Only messages after date (YYYY-MM-DD) |
| -l, --limit | Max results (default: 10) |
| -c, --context | Messages before/after (default: 2) |$3
When installed as a plugin, you get:
Skill (auto-invoked): Claude automatically searches messages when you ask things like:
- "What did Mom say about dinner?"
- "Who texted me recently?"
- "Find messages about the trip"
Slash Commands:
| Command | Description |
|---------|-------------|
|
/messages:search | Fuzzy search with optional filters |
| /messages:recent | Show most recent messages |
| /messages:contacts | List contacts by activity |
| /messages:conversations | List conversations with message counts |
| /messages:from "Name" | Messages from a specific person |
| /messages:thread "Name" | Full conversation thread |
| /messages:browse | Alias for browse commands |$3
When installed as an MCP server, Claude Code can use these tools:
| Tool | Description |
|------|-------------|
|
search_messages | Search messages with fuzzy matching |
| recent_messages | Get most recent messages |
| list_contacts | List contacts by activity |
| list_conversations | List conversations with counts |
| get_thread | Get conversation thread with a contact |
| get_message_stats | Get index statistics |#### Manual MCP Configuration
For Claude Desktop or VS Code, add to your MCP configuration:
`json
{
"mcpServers": {
"messages": {
"command": "npx",
"args": ["-y", "@cardmagic/messages", "--mcp"]
}
}
}
`How It Works
1. Auto-Indexing: On first search (or when new messages are detected), the tool automatically:
- Reads your Apple Messages SQLite database
- Builds a SQLite FTS5 full-text search index
- Creates a MiniSearch fuzzy search index
- Resolves contact names from your Address Book
2. Searching: Queries both indexes for best results with typo tolerance
3. Storage: Index files are stored in
~/.messages/:
- index.db - SQLite FTS5 database
- fuzzy.json - MiniSearch index
- stats.json` - Index statisticsMIT