Messages

messages

Fuzzy search and browse Apple Messages (iMessage/SMS) from the command line, as a Claude Code plugin, or as an MCP server.

Features

• 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

Requirements

• macOS (reads from Apple Messages database)
• Node.js 22+
• Full Disk Access permission for your terminal (to read ~/Library/Messages/chat.db)

Installation

Homebrew

brew install cardmagic/tap/messages

npm

npm install -g @cardmagic/messages

Claude Code Plugin (recommended)

Install as a plugin to get skills (auto-invoked) and slash commands:

# Add the marketplaceclaude plugin marketplace add cardmagic/ai-marketplace
# Install the pluginclaude plugin install messages@cardmagic

This gives you:

• Skill: Claude automatically searches messages when you ask about texts/iMessages
• Slash commands: /messages:search, /messages:recent, /messages:from, and more

MCP Server

For 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/messagesclaude mcp add --transport stdio messages -- messages --mcp

From source

git clone https://github.com/cardmagic/messages.gitcd messagesmake install
# Then add as plugin OR MCP server:claude plugin marketplace add cardmagic/ai-marketplaceclaude plugin install messages@cardmagic# ORclaude 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

CLI

Browse Commands

# Show most recent messages (who texted me?)messages recent
# List contacts by recent activitymessages contacts --limit 10
# List conversations with message countsmessages conversations
# Show recent messages from someonemessages from "Mom"
# Show full conversation threadmessages thread "John" --after 2024-12-01

Search Commands

# Search for messages (index auto-builds on first search)messages search "coffee tomorrow"
# Filter by sendermessages search "dinner" --from "Mom"
# Filter by datemessages search "meeting" --after 2024-01-01
# Adjust result count and contextmessages search "project" --limit 20 --context 5
# Show index statisticsmessages stats
# Force rebuild the indexmessages index

Search Options

Claude Code Plugin

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:

MCP Server

When installed as an MCP server, Claude Code can use these tools:

Manual MCP Configuration

For Claude Desktop or VS Code, add to your MCP configuration:

{  "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 statistics

License

MIT