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: Conduct fuzzy searches with typo tolerance across all your messages.
• Browse recent: Browse recent messages, contacts, and conversations.
• Contact resolution: Display names instead of phone numbers.
• Context display: View messages before and after each match.
• Filter by sender or date range: Filter search results by sender or date range.
• Auto - indexing: Automatically rebuild the index when new messages are detected.
• Multiple interfaces: Use the CLI, MCP server, or Claude Code plugin.

📦 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 marketplace
claude plugin marketplace add cardmagic/ai-marketplace

# Install the plugin
claude plugin install messages@cardmagic

This provides you with:

• 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/messages
claude mcp add --transport stdio messages -- messages --mcp

From source

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

💡 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 Examples

CLI

Browse Commands

# 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 Commands

# 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

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"]
    }
  }
}

🔧 Technical Details

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