MCP server de WhatsApp Chat Reader
✓ VerificadoPermite que un cliente de IA resuma, busque y razone sobre el historial de chats locales de WhatsApp leyendo la base de datos SQLite local.
También conocido como NabheetCloud/wa-chat-reader, wa-chat-reader
- Stars
- 1
- Herramientas
- 2
- Descargas, 30 días
- 132
- Última versión
- 0.1.0
- Último commit
- 5 jul 2026
- Licencia
- MIT
¿Qué es WhatsApp Chat Reader MCP?
Permite que un cliente de IA resuma, busque y razone sobre el historial de chats locales de WhatsApp leyendo la base de datos SQLite local. Expone 2 herramientas, como get_whatsapp_messages, get_whatsapp_chat_list.
Resumen generado a partir del README del proyecto
Acerca del MCP server de WhatsApp Chat Reader
Esta herramienta te permite resumir y buscar en tus conversaciones privadas de WhatsApp directamente desde un cliente de IA. Funciona leyendo la base de datos local ChatStorage.sqlite que utiliza la aplicación de escritorio de WhatsApp en macOS, Windows o Linux. Debido a que el servidor se ejecuta completamente en tu máquina sin código de red, tus datos de mensajes permanecen locales y solo se comparten con el cliente MCP específico que decidas usar.
Los desarrolladores pueden conectar este servidor a clientes como Claude Desktop o Claude Code usando Python y uv. El servidor proporciona dos herramientas específicas: get_whatsapp_messages para recuperar texto de chats personales o grupales, y get_whatsapp_chat_list para ver los nombres de los chats activos. Para proteger la privacidad y el rendimiento, la variable de entorno WHATSAPP_MAX_DAYS limita qué tan atrás puede buscar la IA, con una ventana predeterminada de 30 días. Los usuarios de macOS deben otorgar Acceso total al disco al proceso para poder acceder al contenedor de la base de datos protegida.
Qué puedes hacer con él
- 1Resumir la actividad reciente de un grupoPide a tu cliente de IA que proporcione un resumen de los mensajes de chats grupales específicos de los últimos días.
- 2Identificar conversaciones activasSolicita una lista de todos los chats de WhatsApp en los que has participado durante la semana actual.
- 3Analizar patrones de mensajeríaGenera un dashboard HTML offline para visualizar tu volumen de mensajería y tus ritmos diarios.
Escrito a partir del README del proyecto. Cada caso de uso se verifica con una cita del mismo.
Cómo instalar WhatsApp Chat Reader MCP
Formatos verificados el 10 nov 2026Añadir a CursorAñadir a GooseInstalar WhatsApp Chat Reader MCP en Claude Code
$ claude mcp add wa-chat-reader -- uvx wa-chat-readerInstalar WhatsApp Chat Reader MCP en Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"wa-chat-reader": {
"command": "uvx",
"args": [
"wa-chat-reader"
]
}
}
}Instalar WhatsApp Chat Reader MCP en VS Code
.vscode/mcp.json
{
"servers": {
"wa-chat-reader": {
"type": "stdio",
"command": "uvx",
"args": [
"wa-chat-reader"
]
}
}
}Instalar WhatsApp Chat Reader MCP en VS Code CLI
$ code --add-mcp '{"name":"wa-chat-reader","type":"stdio","command":"uvx","args":["wa-chat-reader"]}'Instalar WhatsApp Chat Reader MCP en Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"wa-chat-reader": {
"command": "uvx",
"args": [
"wa-chat-reader"
]
}
}
}Instalar WhatsApp Chat Reader MCP en Codex
$ codex mcp add wa-chat-reader -- uvx wa-chat-readerInstalar WhatsApp Chat Reader MCP en Codex config.toml
~/.codex/config.toml
[mcp_servers.wa-chat-reader] command = "uvx" args = ["wa-chat-reader"]
Instalar WhatsApp Chat Reader MCP en Gemini CLI
$ gemini mcp add -s user wa-chat-reader uvx -- wa-chat-readerInstalar WhatsApp Chat Reader MCP en Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"wa-chat-reader": {
"command": "uvx",
"args": [
"wa-chat-reader"
]
}
}
}Herramientas de WhatsApp Chat Reader MCP 2
Detectado desde el READMEget_whatsapp_messagesget_whatsapp_chat_list
| get_whatsapp_messages | — | |
| get_whatsapp_chat_list | — |
Configuración
WHATSAPP_BACKUP_PATHSSemicolon-separated fallback database paths, tried after the primary paths.
WHATSAPP_DB_PATHSSemicolon-separated paths to ChatStorage.sqlite. If unset, a platform default is used.
WHATSAPP_DEBUGSet to 'true' for verbose logging to stderr.
WHATSAPP_LOG_FILEOptional path to also write logs to a file.
WHATSAPP_MAX_DAYSMaximum look-back window in days a caller may request.
| Nombre | Descripción | Tipo |
|---|---|---|
| WHATSAPP_BACKUP_PATHS | Semicolon-separated fallback database paths, tried after the primary paths. | |
| WHATSAPP_DB_PATHS | Semicolon-separated paths to ChatStorage.sqlite. If unset, a platform default is used. | |
| WHATSAPP_DEBUG | Set to 'true' for verbose logging to stderr. | |
| WHATSAPP_LOG_FILE | Optional path to also write logs to a file. | |
| WHATSAPP_MAX_DAYS | Maximum look-back window in days a caller may request. |
Verificaciones automáticas
Ejecutado 14 nov 2026Informe completo →Pasó nuestras verificaciones automáticas. Esto no es una auditoría de seguridad: lee el código y dale al servidor el acceso más limitado que necesite. Cómo funcionan las verificaciones
- Repositorio de origen vinculado y accesiblenabheetcloud/wa-chat-reader is public and reachablegithub.com/nabheetcloud/wa-chat-reader ↗Aprobado
- El paquete indica este repositorio como su origenwa-chat-reader names nabheetcloud/wa-chat-reader as sourcepypi.org/project/wa-chat-reader/ ↗Aprobado
- Procedencia de la compilación (atestación de Sigstore)No build attestation published for this releaseNo verificado
- Licencia de código abierto (OSI)MITspdx.org/licenses/MIT.html ↗Aprobado
- Commit o lanzamiento en el último añoLast commit or release 2026-07-05github.com/nabheetcloud/wa-chat-reader ↗Aprobado
- OpenSSF ScorecardNo verificado
- El nombre del paquete no es similar a un paquete popularNo popular package one edit away from wa-chat-readerAprobado
- No hay avisos críticos en el paquete ni en sus dependencias29 resolved dependencies checked; no critical advisoryosv.dev ↗Aprobado
- Sin instrucciones ocultas para el modelo2 tool descriptions and the README read; no override phrases, credential paths or hidden charactersAprobado
- Las herramientas destructivas están etiquetadasNo tool named like delete, drop or execAprobado
- El endpoint remoto responde al handshake de MCPNo verificado
README
Ver en GitHubwa-chat-reader
Unofficial, read-only MCP server for your local WhatsApp chat history.
wa-chat-reader reads the WhatsApp ChatStorage.sqlite database that the WhatsApp
desktop app keeps on your machine and exposes two tools to any MCP client (Claude
Code, Claude Desktop, etc.) so you can summarize, search, and reason over your own
messages. Everything runs locally — no data ever leaves your computer.
⚠️ Not affiliated with, endorsed by, or connected to WhatsApp or Meta. "WhatsApp" is a trademark of Meta Platforms, Inc. This is an independent, unofficial tool that only reads a database WhatsApp already stores on your device.
Privacy & security
This tool touches highly sensitive data — your private conversations. Read this first.
- Read-only. The database is opened with SQLite
mode=ro&immutable=1; the server never writes to, modifies, or deletes anything. - Local-only. There is no network code. Messages are returned to your MCP client and nowhere else. Whatever LLM/client you connect will, of course, see the message text you ask it to read — you control that by choosing which client to run.
- Your consent, your data. Only run this against your own device and your own chats. Do not use it to access anyone else's messages.
- macOS access. The WhatsApp database lives in a protected group container. The
process running this server needs Full Disk Access
(System Settings → Privacy & Security → Full Disk Access), or point
WHATSAPP_DB_PATHSat a readable copy you export yourself. - Scope control.
WHATSAPP_MAX_DAYS(default 30) caps how far back any single call can read.
Install
Requires Python ≥ 3.10. Recommended: uv so the server
runs in an isolated environment.
# one-shot run (no install)
uvx wa-chat-reader
# or install with pip
pip install wa-chat-reader
wa-chat-reader
Use in Claude Code
claude mcp add wa-chat-reader -- uvx wa-chat-reader
Or install as a plugin (see the marketplace section below), then ask Claude things like:
- "Summarize my unread WhatsApp group chats from the last 3 days."
- "List the WhatsApp chats I've been active in this week."
Configuration
All configuration is via environment variables (all optional):
| Variable | Default | Description |
|---|---|---|
WHATSAPP_DB_PATHS |
platform default | ;-separated candidate paths to ChatStorage.sqlite (first readable wins) |
WHATSAPP_BACKUP_PATHS |
— | ;-separated fallback paths, tried after the primary paths |
WHATSAPP_MAX_DAYS |
30 |
Max look-back window (days) a caller may request |
WHATSAPP_DEBUG |
false |
true for verbose logging to stderr |
WHATSAPP_LOG_FILE |
— | Optional path to also write logs to a file |
Default database locations:
| OS | Path |
|---|---|
| macOS | ~/Library/Group Containers/group.net.whatsapp.WhatsApp.shared/ChatStorage.sqlite |
| Windows | ~/AppData/Roaming/WhatsApp/Databases/ChatStorage.sqlite |
| Linux | ~/.local/share/whatsapp/ChatStorage.sqlite |
Tools
| Tool | Description |
|---|---|
get_whatsapp_messages |
Concatenated message text from group and personal chats within a look-back window. Params: days (1–max), chat_type (all/groups/personal). Read-only. |
get_whatsapp_chat_list |
Active chat names (no message bodies) within a look-back window. Param: days. Read-only. |
Both tools are annotated readOnlyHint: true.
Bonus: activity dashboard
whatsapp_dashboard.py renders a self-contained, offline HTML dashboard of your
messaging activity (volume over time, daily/weekly rhythm, top chats) straight from
the same database:
python3 whatsapp_dashboard.py # -> whatsapp_dashboard.html
The generated HTML contains real contact names — it is git-ignored and meant to stay local.
Develop
git clone https://github.com/NabheetCloud/wa-chat-reader
cd wa-chat-reader
pip install -e .
python3 simple_whatsapp_mcp.py # run from source without installing
License
MIT © 2026 Nabheet Madan
Preguntas sobre WhatsApp Chat Reader MCP
¿Cómo agrego WhatsApp Chat Reader MCP a Claude Code?
Ejecuta claude mcp add wa-chat-reader -- uvx wa-chat-reader en tu terminal. Añade --scope user para que esté disponible en todos los proyectos.
¿Cómo agrego WhatsApp Chat Reader MCP a Cursor?
Abre ~/.cursor/mcp.json y añade el servidor en mcpServers, usando la configuración de Cursor que se muestra en la sección de instalación de arriba.
¿Qué herramientas proporciona WhatsApp Chat Reader MCP?
Expone 2 herramientas, incluidas get_whatsapp_messages, get_whatsapp_chat_list.
¿Mis datos de WhatsApp se envían a la nube?
No, todo se ejecuta localmente y ningún dato sale de tu computadora.
¿Puede este servidor modificar o eliminar mis mensajes?
No, el servidor es de solo lectura y utiliza el modo SQLite que impide escribir, modificar o eliminar cualquier cosa.
¿Qué permisos se necesitan en macOS para usar esto?
El proceso requiere Acceso total al disco en los Ajustes del Sistema porque la base de datos de WhatsApp se encuentra en un contenedor de grupo protegido.
¿Qué tan atrás puede leer mis mensajes la IA?
La ventana de búsqueda está limitada por la variable WHATSAPP_MAX_DAYS, que por defecto es de 30 días.