messages

messages

Búsqueda difusa y navegación de Apple Messages (iMessage/SMS) desde la línea de comandos, como plugin de Claude Code, o como servidor MCP.

Características

• Búsqueda difusa con tolerancia a errores tipográficos en todos tus mensajes
• Navegar recientes mensajes, contactos y conversaciones
• Resolución de contactos - muestra nombres en lugar de números de teléfono
• Visualización de contexto - ver mensajes antes/después de cada coincidencia
• Filtrar por remitente o rango de fechas
• Auto-indexación - el índice se reconstruye automáticamente cuando se detectan nuevos mensajes
• Múltiples interfaces - CLI, servidor MCP, o plugin de Claude Code

Requisitos

• macOS (lee de la base de datos de Apple Messages)
• Node.js 22+
• Permiso de Acceso Total al Disco para tu terminal (para leer ~/Library/Messages/chat.db)

Instalación

Homebrew

brew install cardmagic/tap/messages

npm

npm install -g @cardmagic/messages

Plugin de Claude Code (recomendado)

Instala como plugin para obtener habilidades (invocadas automáticamente) y comandos de barra:

# Add the marketplace
claude plugin marketplace add cardmagic/ai-marketplace

# Install the plugin
claude plugin install messages@cardmagic

Esto te proporciona:

• Habilidad: Claude busca mensajes automáticamente cuando preguntas sobre textos/iMessages
• Comandos de barra: /messages:search, /messages:recent, /messages:from, y más

Servidor MCP

Para acceso directo a herramientas MCP sin el plugin:

claude mcp add --transport stdio messages -- npx -y @cardmagic/messages --mcp

O instala globalmente primero:

npm install -g @cardmagic/messages
claude mcp add --transport stdio messages -- messages --mcp

Desde el código fuente

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

Conceder Acceso Total al Disco

La herramienta necesita leer tu base de datos de Messages en ~/Library/Messages/chat.db:

1. Abre Configuración del Sistema > Privacidad y Seguridad > Acceso Total al Disco
2. Haz clic en + y añade tu aplicación de terminal (Terminal.app, iTerm, Warp, etc.)
3. Reinicia tu terminal

Uso

CLI

Comandos de Navegación

# 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

Comandos de Búsqueda

# 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

Opciones de Búsqueda

Opción	Descripción
-f, --from <sender>	Filtrar por nombre o teléfono del remitente
-a, --after <date>	Solo mensajes después de la fecha (AAAA-MM-DD)
-l, --limit <n>	Máximo de resultados (predeterminado: 10)
-c, --context <n>	Mensajes antes/después (predeterminado: 2)

Plugin de Claude Code

Cuando se instala como plugin, obtienes:

Habilidad (invocada automáticamente): Claude busca mensajes automáticamente cuando preguntas cosas como:

• "¿Qué dijo mamá sobre la cena?"
• "¿Quién me envió mensajes recientemente?"
• "Encuentra mensajes sobre el viaje"

Comandos de Barra:

Comando	Descripción
/messages:search <query>	Búsqueda difusa con filtros opcionales
/messages:recent	Mostrar mensajes más recientes
/messages:contacts	Listar contactos por actividad
/messages:conversations	Listar conversaciones con conteos de mensajes
/messages:from "Name"	Mensajes de una persona específica
/messages:thread "Name"	Hilo de conversación completo
/messages:browse <cmd>	Alias para comandos de navegación

Servidor MCP

Cuando se instala como servidor MCP, Claude Code puede usar estas herramientas:

Herramienta	Descripción
search_messages	Buscar mensajes con coincidencia difusa
recent_messages	Obtener mensajes más recientes
list_contacts	Listar contactos por actividad
list_conversations	Listar conversaciones con conteos
get_thread	Obtener hilo de conversación con un contacto
get_message_stats	Obtener estadísticas del índice

Configuración Manual de MCP

Para Claude Desktop o VS Code, añade a tu configuración de MCP:

{
  "mcpServers": {
    "messages": {
      "command": "npx",
      "args": ["-y", "@cardmagic/messages", "--mcp"]
    }
  }
}

Cómo Funciona

1. Auto-indexación: En la primera búsqueda (o cuando se detectan nuevos mensajes), la herramienta automáticamente:

   • Lee tu base de datos SQLite de Apple Messages
   • Construye un índice de búsqueda de texto completo SQLite FTS5
   • Crea un índice de búsqueda difusa MiniSearch
   • Resuelve nombres de contactos desde tu Agenda

2. Búsqueda: Consulta ambos índices para obtener los mejores resultados con tolerancia a errores tipográficos

3. Almacenamiento: Los archivos de índice se almacenan en ~/.messages/:

   • index.db - Base de datos SQLite FTS5
   • fuzzy.json - Índice MiniSearch
   • stats.json - Estadísticas del índice

Licencia

MIT