{
  "markdown": "# messages\n\nFuzzy search and browse Apple Messages (iMessage/SMS) from the command line, as a Claude Code plugin, or as an MCP server.\n\n## Features\n\n- **Fuzzy search** with typo tolerance across all your messages\n- **Browse recent** messages, contacts, and conversations\n- **Contact resolution** - shows names instead of phone numbers\n- **Context display** - see messages before/after each match\n- **Filter by sender** or date range\n- **Auto-indexing** - index automatically rebuilds when new messages are detected\n- **Multiple interfaces** - CLI, MCP server, or Claude Code plugin\n\n## Requirements\n\n- macOS (reads from Apple Messages database)\n- Node.js 22+\n- Full Disk Access permission for your terminal (to read `~/Library/Messages/chat.db`)\n\n## Installation\n\n### Homebrew\n\n```bash\nbrew install cardmagic/tap/messages\n```\n\n### npm\n\n```bash\nnpm install -g @cardmagic/messages\n```\n\n### Claude Code Plugin (recommended)\n\nInstall as a plugin to get skills (auto-invoked) and slash commands:\n\n```bash\n# Add the marketplace\nclaude plugin marketplace add cardmagic/ai-marketplace\n\n# Install the plugin\nclaude plugin install messages@cardmagic\n```\n\nThis gives you:\n- **Skill**: Claude automatically searches messages when you ask about texts/iMessages\n- **Slash commands**: `/messages:search`, `/messages:recent`, `/messages:from`, and more\n\n### MCP Server\n\nFor direct MCP tool access without the plugin:\n\n```bash\nclaude mcp add --transport stdio messages -- npx -y @cardmagic/messages --mcp\n```\n\nOr install globally first:\n\n```bash\nnpm install -g @cardmagic/messages\nclaude mcp add --transport stdio messages -- messages --mcp\n```\n\n### From source\n\n```bash\ngit clone https://github.com/cardmagic/messages.git\ncd messages\nmake install\n\n# Then add as plugin OR MCP server:\nclaude plugin marketplace add cardmagic/ai-marketplace\nclaude plugin install messages@cardmagic\n# OR\nclaude mcp add --transport stdio messages -- messages --mcp\n```\n\n## Granting Full Disk Access\n\nThe tool needs to read your Messages database at `~/Library/Messages/chat.db`:\n\n1. Open **System Settings** > **Privacy & Security** > **Full Disk Access**\n2. Click **+** and add your terminal app (Terminal.app, iTerm, Warp, etc.)\n3. Restart your terminal\n\n## Usage\n\n### CLI\n\n#### Browse Commands\n\n```bash\n# Show most recent messages (who texted me?)\nmessages recent\n\n# List contacts by recent activity\nmessages contacts --limit 10\n\n# List conversations with message counts\nmessages conversations\n\n# Show recent messages from someone\nmessages from \"Mom\"\n\n# Show full conversation thread\nmessages thread \"John\" --after 2024-12-01\n```\n\n#### Search Commands\n\n```bash\n# Search for messages (index auto-builds on first search)\nmessages search \"coffee tomorrow\"\n\n# Filter by sender\nmessages search \"dinner\" --from \"Mom\"\n\n# Filter by date\nmessages search \"meeting\" --after 2024-01-01\n\n# Adjust result count and context\nmessages search \"project\" --limit 20 --context 5\n\n# Show index statistics\nmessages stats\n\n# Force rebuild the index\nmessages index\n```\n\n#### Search Options\n\n| Option | Description |\n|--------|-------------|\n| `-f, --from <sender>` | Filter by sender name or phone |\n| `-a, --after <date>` | Only messages after date (YYYY-MM-DD) |\n| `-l, --limit <n>` | Max results (default: 10) |\n| `-c, --context <n>` | Messages before/after (default: 2) |\n\n### Claude Code Plugin\n\nWhen installed as a plugin, you get:\n\n**Skill** (auto-invoked): Claude automatically searches messages when you ask things like:\n- \"What did Mom say about dinner?\"\n- \"Who texted me recently?\"\n- \"Find messages about the trip\"\n\n**Slash Commands**:\n\n| Command | Description |\n|---------|-------------|\n| `/messages:search <query>` | Fuzzy search with optional filters |\n| `/messages:recent` | Show most recent messages |\n| `/messages:contacts` | List contacts by activity |\n| `/messages:conversations` | List conversations with message counts |\n| `/messages:from \"Name\"` | Messages from a specific person |\n| `/messages:thread \"Name\"` | Full conversation thread |\n| `/messages:browse <cmd>` | Alias for browse commands |\n\n### MCP Server\n\nWhen installed as an MCP server, Claude Code can use these tools:\n\n| Tool | Description |\n|------|-------------|\n| `search_messages` | Search messages with fuzzy matching |\n| `recent_messages` | Get most recent messages |\n| `list_contacts` | List contacts by activity |\n| `list_conversations` | List conversations with counts |\n| `get_thread` | Get conversation thread with a contact |\n| `get_message_stats` | Get index statistics |\n\n#### Manual MCP Configuration\n\nFor Claude Desktop or VS Code, add to your MCP configuration:\n\n```json\n{\n  \"mcpServers\": {\n    \"messages\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@cardmagic/messages\", \"--mcp\"]\n    }\n  }\n}\n```\n\n## How It Works\n\n1. **Auto-Indexing**: On first search (or when new messages are detected), the tool automatically:\n   - Reads your Apple Messages SQLite database\n   - Builds a SQLite FTS5 full-text search index\n   - Creates a MiniSearch fuzzy search index\n   - Resolves contact names from your Address Book\n\n2. **Searching**: Queries both indexes for best results with typo tolerance\n\n3. **Storage**: Index files are stored in `~/.messages/`:\n   - `index.db` - SQLite FTS5 database\n   - `fuzzy.json` - MiniSearch index\n   - `stats.json` - Index statistics\n\n## License\n\nMIT\n",
  "bytes": 5320,
  "sha": "b3d5ba74c557ac79a91ae465ad2a86c11ef6c3c5e59505c792db880bf37a3c6b",
  "repo_slug": "cardmagic/messages",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_cardmagic_messages_d9b478ec/readme"
}