messages

messages

Pesquisa difusa e navegação pelo Apple Messages (iMessage/SMS) a partir da linha de comando, como plugin do Claude Code ou como servidor MCP.

Recursos

• Pesquisa difusa com tolerância a erros de digitação em todas as suas mensagens
• Navegar pelos recentes - mensagens, contatos e conversas
• Resolução de contatos - mostra nomes em vez de números de telefone
• Exibição de contexto - veja mensagens antes/depois de cada correspondência
• Filtrar por remetente ou intervalo de datas
• Indexação automática - o índice é reconstruído automaticamente quando novas mensagens são detectadas
• Múltiplas interfaces - CLI, servidor MCP ou plugin do Claude Code

Requisitos

• macOS (lê do banco de dados do Apple Messages)
• Node.js 22+
• Permissão de Acesso Total ao Disco para o seu terminal (para ler ~/Library/Messages/chat.db)

Instalação

Homebrew

brew install cardmagic/tap/messages

npm

npm install -g @cardmagic/messages

Plugin do Claude Code (recomendado)

Instale como plugin para obter skills (invocadas automaticamente) e comandos de barra:

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

# Install the plugin
claude plugin install messages@cardmagic

Isso oferece:

• Skill: o Claude pesquisa mensagens automaticamente quando você pergunta sobre textos/iMessages
• Comandos de barra: /messages:search, /messages:recent, /messages:from e mais

Servidor MCP

Para acesso direto às ferramentas MCP sem o plugin:

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

Ou instale globalmente primeiro:

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

A partir do código-fonte

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

Concedendo Acesso Total ao Disco

A ferramenta precisa ler seu banco de dados de Mensagens em ~/Library/Messages/chat.db:

1. Abra Ajustes do Sistema > Privacidade e Segurança > Acesso Total ao Disco
2. Clique em + e adicione seu aplicativo de terminal (Terminal.app, iTerm, Warp, etc.)
3. Reinicie o terminal

Uso

CLI

Comandos de Navegação

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

# 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

Opções de Pesquisa

Opção	Descrição
-f, --from <sender>	Filtrar por nome ou telefone do remetente
-a, --after <date>	Apenas mensagens após a data (AAAA-MM-DD)
-l, --limit <n>	Máximo de resultados (padrão: 10)
-c, --context <n>	Mensagens antes/depois (padrão: 2)

Plugin do Claude Code

Quando instalado como plugin, você obtém:

Skill (invocada automaticamente): o Claude pesquisa mensagens automaticamente quando você pergunta coisas como:

• "O que a mãe disse sobre o jantar?"
• "Quem me mandou mensagem recentemente?"
• "Encontre mensagens sobre a viagem"

Comandos de Barra:

Comando	Descrição
/messages:search <query>	Pesquisa difusa com filtros opcionais
/messages:recent	Mostra as mensagens mais recentes
/messages:contacts	Lista contatos por atividade
/messages:conversations	Lista conversas com contagens de mensagens
/messages:from "Name"	Mensagens de uma pessoa específica
/messages:thread "Name"	Tópico completo da conversa
/messages:browse <cmd>	Alias para comandos de navegação

Servidor MCP

Quando instalado como servidor MCP, o Claude Code pode usar estas ferramentas:

Ferramenta	Descrição
search_messages	Pesquisa mensagens com correspondência difusa
recent_messages	Obtém as mensagens mais recentes
list_contacts	Lista contatos por atividade
list_conversations	Lista conversas com contagens
get_thread	Obtém o tópico da conversa com um contato
get_message_stats	Obtém estatísticas do índice

Configuração Manual do MCP

Para Claude Desktop ou VS Code, adicione à sua configuração MCP:

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

Como Funciona

1. Indexação Automática: Na primeira pesquisa (ou quando novas mensagens são detectadas), a ferramenta automaticamente:

   • Lê seu banco de dados SQLite do Apple Messages
   • Constrói um índice de pesquisa de texto completo SQLite FTS5
   • Cria um índice de pesquisa difusa MiniSearch
   • Resolve nomes de contatos da sua Agenda

2. Pesquisa: Consulta ambos os índices para obter os melhores resultados com tolerância a erros de digitação

3. Armazenamento: Os arquivos de índice são armazenados em ~/.messages/:

   • index.db - banco de dados SQLite FTS5
   • fuzzy.json - índice MiniSearch
   • stats.json - estatísticas do índice

Licença

MIT