convez.ai
MCP ServerProdutividadeIntermediário
LevNyyon

WhatsApp Digest Local

LevNyyon/whatsapp-digest-local

Resumo inteligente de WhatsApp local, sem cloud, direto no Claude

Ver no GitHub
InicialPluginScore · de 0 a 100

MCP server que transforma seus chats recentes do WhatsApp em um resumo priorizado dentro do Claude, rodando 100% localmente na sua máquina, sem envio de mensagens nem armazenamento em cloud. Permite busca por linguagem natural em todo seu histórico de mensagens, identificando automaticamente o que precisa de resposta, é urgente ou é apenas ruído.

Instalação

$npx convez-ai LevNyyon/whatsapp-digest-local

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
4
Forks
0
Acompanhando
0
Saúde
42%
Último commit
há 4 meses
Versão
v0.2.0
Issues abertas
0
Contribuidores
1

Casos de uso

  • Gerar resumo diário de chats prioritizados para não perder o que é importante
  • Buscar conversas específicas por tema ou pessoa em linguagem natural
  • Revisar rapidamente atividades em aberto antes de começar o dia

Veredito

Solução bem pensada que responde a uma real necessidade de produtividade sem sacrificar privacidade — toda execução ocorre localmente. Implementação técnica sólida (MCP, Chromium headless) e design cauteloso (sem função de envio, sem upload de dados). Restrições conhecidas (histórico limitado ao que WhatsApp Web sincroniza) são documentadas honestamente.

README

A tradução para o português deste README ainda está na fila.

WhatsApp Digest (local)

A small, local, read-only assistant for your AI app. It turns your recent WhatsApp chats into a short, prioritized digest, and it lets you search your whole history in plain language.

Ask for a digest and you get back what needs a reply, what is time-sensitive, and what is just noise, plus the top few things to handle today. Or ask a question like "where did I discuss the lease" and it searches your chats and returns only the messages that matter.

It runs entirely on your own machine. There is no send function in the code. It only reads.


What it is

WhatsApp Digest is an MCP server. It holds a WhatsApp Web session locally and exposes your messages to your AI assistant as a few read-only tools. The assistant does the thinking: it writes the brief, or searches your history for whatever you ask about. You add it to your AI app once, link your phone once, and then ask.

It is the open, minimal core of a much larger operator hub, given away free.

What it does

  • Links to your WhatsApp via a QR scan (like WhatsApp Web), then remembers the session.
  • Builds a prioritized digest of recent activity: needs a reply / time-sensitive / FYI, with unread counts.
  • Searches your history in plain language (up to about six months back) and returns only the messages that match a topic or person.

What it does NOT do

  • It never sends messages. There is no send code path, by design.
  • It is not a cloud service. Nothing is hosted; there is no server you sign up for.
  • It does not store or upload your messages. This tool keeps no database. (See the privacy note below about your AI app itself.)
  • It can only see what WhatsApp Web has synced to your machine. Recent history is reliable; very old archives may not be there.

How it works

Your phone ──link──► WhatsApp helper (one shared local process) ──HTTP──► MCP server(s) ──► your AI app
  • A single background helper holds one WhatsApp Web session (headless Chromium, like the WhatsApp Web you use in a browser). It listens on a fixed local port and outlives app restarts, so the session persists, you link once.
  • Your MCP client starts an MCP server per chat/session; each one is a thin client that forwards to that single helper. Open as many as you like, they all share one session, so there are no duplicate logins and no re-scanning.
  • Your AI app is the brain. No extra LLM API key needed, the app's own model does the reasoning.

Requirements

  • Node.js 18+
  • An MCP client that can run local servers, Claude Desktop, Claude Code, Cursor, VS Code (Copilot), Windsurf, Cline, Zed, or your own agent. (The steps below use Claude Desktop; see Works with any MCP client for the rest.)
  • A WhatsApp account on your phone

Install

git clone https://github.com/LevNyyon/whatsapp-digest-local.git
cd whatsapp-digest-local
npm install

First install downloads a Chromium for WhatsApp Web (~150 MB). One time only.

Add it to Claude Desktop. Easiest, run the helper (it merges into your config and uses an absolute node path, which macOS GUI apps need):

node scripts/apply-to-claude-desktop.mjs

Or do it by hand. Open the config:

  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
  • Windows: %APPDATA%\Claude\claude_desktop_config.json
{
  "mcpServers": {
    "whatsapp-digest": {
      "command": "/absolute/path/to/node",
      "args": ["/absolute/path/to/whatsapp-digest-local/src/index.js"]
    }
  }
}

On macOS, use the absolute path to node (find it with which node). GUI apps don't inherit your shell PATH, so a bare "node" often fails to launch.

Restart Claude Desktop.

First run, link your phone

In Claude, say:

link my whatsapp

A page opens with a QR code. On your phone: WhatsApp → Settings → Linked Devices → Link a Device → scan it. The page flips to "Linked" and the session is saved locally, you won't scan again.

Use it

give me my whatsapp digest

or

what did I miss in the last 6 hours?

Works with any MCP client

This is a standard local MCP server, not Claude-specific. Anything that can run a local (stdio) MCP server can use it: Claude Desktop, Claude Code, Cursor, VS Code (Copilot), Windsurf, Cline, Zed, or your own agent built on an MCP SDK. The model in that app does the digest reasoning, so any capable model works.

Most clients use the same config shape, only the file location differs per app:

{
  "mcpServers": {
    "whatsapp-digest": {
      "command": "/absolute/path/to/node",
      "args": ["/absolute/path/to/whatsapp-digest-local/src/index.js"]
    }
  }
}

You get the same five tools and the whatsapp_digest prompt. The one limit: a cloud-only client that accepts only remote MCP servers won't work, the WhatsApp session has to run locally on your machine.

The tools (all read-only)

ToolWhat it does
whatsapp_statusIs WhatsApp linked yet?
link_whatsappOpens the QR page to link your phone
list_chatsRecent chats + unread counts
get_messagesMessages from the last N hours (optionally one chat)
reset_whatsappForce a clean restart of the helper if it ever gets stuck (keeps your login)

The helper is self-healing: it clears stale browser locks on start (so a crash can't wedge it), and auto-reconnects with backoff if WhatsApp drops. If it ever gets truly stuck, ask Claude to "reset whatsapp".

There is also a built-in whatsapp_digest prompt and an optional Skill (skill/SKILL.md) that teach Claude how to format a good brief.

⚠️ Safety & caveats, read this

  • Unofficial. WhatsApp has no public API for this. whatsapp-web.js automates WhatsApp Web. Automating WhatsApp is against WhatsApp's Terms of Service.
  • Ban risk. Your number can be rate-limited or banned. Use a number you are comfortable risking. This project is read-only specifically to stay on the lower-risk side, but the risk is not zero.
  • Privacy, your messages go to Claude when you ask for a digest. This tool stores and uploads nothing on its own. But when Claude reads your messages to write the brief, that text is sent to Claude (Anthropic) like any other prompt. Don't digest chats you wouldn't paste into Claude.
  • It can break. When WhatsApp changes WhatsApp Web, whatsapp-web.js may stop working until it's updated. That's the nature of unofficial tooling.
  • One session per number. You can't run two WhatsApp Web automations on the same number at once.
  • Not affiliated with WhatsApp or Meta in any way.
  • No warranty. Provided "as is" (see LICENSE). You use it at your own risk.

Configuration

Env varDefaultPurpose
WA_SESSION_DIR<install>/.wa-sessionWhere the WhatsApp session is saved
WA_DAEMON_PORT47291Fixed local port the shared helper listens on
WA_WEB_VERSIONpinnedWhatsApp Web version to use (override if it goes stale)

Security

The local helper binds to localhost and only answers requests that come from your own machine. It validates the Host header and rejects cross-site requests, which closes DNS rebinding and CSRF (a malicious web page you visit cannot reach the helper through your browser).

Two things to know:

  • The helper has no password, so any program already running on your machine as you could talk to it. On a personal machine that is the same trust level as your WhatsApp session sitting on disk.
  • That session (.wa-session) is your WhatsApp login. It is gitignored and never leaves your machine. Keep it private.

Roadmap

  • v2, auto mode: a small always-on background process (cron) that builds the digest every morning and sends it to your own WhatsApp number, even when Claude is closed. (Needs an Anthropic API key, since there's no human in the loop.)
  • One-click install: package as a .dxt Desktop Extension so install becomes a double-click with no terminal. A current-format manifest.json is included.

Changelog

See CHANGELOG.md.

License

MIT, free to use, modify, and distribute. Do what you like.

Ver o original no GitHub

Bom para

Relacionados