npx claudepluginhub cardmagic/messagesFuzzy search Apple Messages/iMessage conversations
cardmagicShare bugs, ideas, or general feedback.
Fuzzy search and browse Apple Messages (iMessage/SMS) from the command line, as a Claude Code plugin, or as an MCP server.
~/Library/Messages/chat.db)brew install cardmagic/tap/messages
npm install -g @cardmagic/messages
Install as a plugin to get skills (auto-invoked) and slash commands:
# Add the marketplace
claude plugin marketplace add cardmagic/ai-marketplace
# Install the plugin
claude plugin install messages@cardmagic
This gives you:
/messages:search, /messages:recent, /messages:from, and moreFor direct MCP tool access without the plugin:
claude mcp add --transport stdio messages -- npx -y @cardmagic/messages --mcp
Or install globally first:
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
The tool needs to read your Messages database at ~/Library/Messages/chat.db:
# 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
| Option | Description |
|---|---|
-f, --from <sender> | Filter by sender name or phone |
-a, --after <date> | Only messages after date (YYYY-MM-DD) |
-l, --limit <n> | Max results (default: 10) |
-c, --context <n> | Messages before/after (default: 2) |
When installed as a plugin, you get:
Skill (auto-invoked): Claude automatically searches messages when you ask things like:
Slash Commands:
| Command | Description |
|---|---|
/messages:search <query> | 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 <cmd> | Alias for browse commands |
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 |
For Claude Desktop or VS Code, add to your MCP configuration:
{
"mcpServers": {
"messages": {
"command": "npx",
"args": ["-y", "@cardmagic/messages", "--mcp"]
}
}
}