WhatsApp Chat Reader MCP server
✓ 인증됨로컬 SQLite 데이터베이스를 읽어 AI 클라이언트가 로컬 WhatsApp 채팅 기록을 요약, 검색 및 추론할 수 있도록 합니다.
다른 이름 NabheetCloud/wa-chat-reader, wa-chat-reader
- 스타
- 1
- Tools
- 2
- 다운로드, 30일
- 132
- 최신 버전
- 0.1.0
- 마지막 커밋
- 2026년 7월 5일
- 라이선스
- MIT
WhatsApp Chat Reader MCP란?
로컬 SQLite 데이터베이스를 읽어 AI 클라이언트가 로컬 WhatsApp 채팅 기록을 요약, 검색 및 추론할 수 있도록 합니다. 2개 도구를 제공합니다. 예: get_whatsapp_messages, get_whatsapp_chat_list.
프로젝트 README에서 생성된 요약
WhatsApp Chat Reader MCP server 정보
이 도구를 사용하면 AI 클라이언트 내에서 개인 WhatsApp 대화를 요약하고 검색할 수 있습니다. macOS, Windows 또는 Linux에서 WhatsApp 데스크톱 애플리케이션이 사용하는 로컬 ChatStorage.sqlite 데이터베이스를 읽는 방식으로 작동합니다. 서버가 네트워크 코드 없이 사용자의 기기에서 완전히 실행되므로 메시지 데이터는 로컬에 유지되며 사용자가 선택한 특정 MCP 클라이언트와만 공유됩니다.
개발자는 Python과 uv를 사용하여 이 서버를 Claude Desktop 또는 Claude Code와 같은 클라이언트에 연결할 수 있습니다. 서버는 개인 또는 그룹 채팅에서 텍스트를 가져오는 get_whatsapp_messages와 활성 채팅 이름을 확인하는 get_whatsapp_chat_list라는 두 가지 특정 도구를 제공합니다. 개인정보 보호와 성능을 위해 WHATSAPP_MAX_DAYS 환경 변수로 AI의 조회 범위를 제한하며 기본값은 30일입니다. macOS 사용자는 보호된 데이터베이스 컨테이너에 접근하기 위해 프로세스에 전체 디스크 접근 권한을 부여해야 합니다.
활용 사례
- 1최근 그룹 활동 요약AI 클라이언트에 지난 며칠 동안 특정 그룹 채팅의 메시지 요약을 요청합니다.
- 2활성 대화 식별이번 주에 참여한 모든 WhatsApp 채팅 목록을 요청합니다.
- 3메시징 패턴 분석메시지 전송량과 일일 패턴을 시각화하는 오프라인 HTML 대시보드를 생성합니다.
프로젝트의 README를 바탕으로 작성되었습니다. 모든 활용 사례는 해당 내용의 인용문과 대조하여 확인합니다.
WhatsApp Chat Reader MCP 설치 방법
형식 확인: 2026년 11월 10일Cursor에 추가Goose에 추가Claude Code에 WhatsApp Chat Reader MCP 설치
$ claude mcp add wa-chat-reader -- uvx wa-chat-readerCursor에 WhatsApp Chat Reader MCP 설치
~/.cursor/mcp.json
{
"mcpServers": {
"wa-chat-reader": {
"command": "uvx",
"args": [
"wa-chat-reader"
]
}
}
}VS Code에 WhatsApp Chat Reader MCP 설치
.vscode/mcp.json
{
"servers": {
"wa-chat-reader": {
"type": "stdio",
"command": "uvx",
"args": [
"wa-chat-reader"
]
}
}
}VS Code CLI에 WhatsApp Chat Reader MCP 설치
$ code --add-mcp '{"name":"wa-chat-reader","type":"stdio","command":"uvx","args":["wa-chat-reader"]}'Claude Desktop에 WhatsApp Chat Reader MCP 설치
claude_desktop_config.json
{
"mcpServers": {
"wa-chat-reader": {
"command": "uvx",
"args": [
"wa-chat-reader"
]
}
}
}Codex에 WhatsApp Chat Reader MCP 설치
$ codex mcp add wa-chat-reader -- uvx wa-chat-readerCodex config.toml에 WhatsApp Chat Reader MCP 설치
~/.codex/config.toml
[mcp_servers.wa-chat-reader] command = "uvx" args = ["wa-chat-reader"]
Gemini CLI에 WhatsApp Chat Reader MCP 설치
$ gemini mcp add -s user wa-chat-reader uvx -- wa-chat-readerGemini settings.json에 WhatsApp Chat Reader MCP 설치
~/.gemini/settings.json
{
"mcpServers": {
"wa-chat-reader": {
"command": "uvx",
"args": [
"wa-chat-reader"
]
}
}
}WhatsApp Chat Reader MCP 도구 2
README에서 감지됨get_whatsapp_messagesget_whatsapp_chat_list
| get_whatsapp_messages | — | |
| get_whatsapp_chat_list | — |
구성
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.
| 이름 | 설명 | 유형 |
|---|---|---|
| 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. |
자동 검사
2026년 11월 14일에 실행됨전체 보고서 →자동 검사를 통과했습니다. 이는 보안 감사가 아닙니다. 코드를 직접 읽고 서버에 필요한 최소한의 권한만 부여하십시오. 검사 방식
- 소스 저장소 연결 및 접근 가능nabheetcloud/wa-chat-reader is public and reachablegithub.com/nabheetcloud/wa-chat-reader ↗통과
- 패키지가 이 저장소를 소스로 명시wa-chat-reader names nabheetcloud/wa-chat-reader as sourcepypi.org/project/wa-chat-reader/ ↗통과
- 빌드 출처(Sigstore 증명)No build attestation published for this release검사되지 않음
- 오픈 소스 라이선스 (OSI)MITspdx.org/licenses/MIT.html ↗통과
- 최근 1년 내 커밋 또는 릴리스Last commit or release 2026-07-05github.com/nabheetcloud/wa-chat-reader ↗통과
- OpenSSF Scorecard검사되지 않음
- 패키지 이름이 인기 패키지와 유사하지 않음No popular package one edit away from wa-chat-reader통과
- 패키지 및 해당 종속성에 중요한 보안 권고 없음29 resolved dependencies checked; no critical advisoryosv.dev ↗통과
- 모델에 대한 숨겨진 지침 없음2 tool descriptions and the README read; no override phrases, credential paths or hidden characters통과
- 파괴적인 도구에 라벨 표시됨No tool named like delete, drop or exec통과
- 원격 엔드포인트가 MCP 핸드셰이크에 응답검사되지 않음
README
GitHub에서 보기wa-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
WhatsApp Chat Reader MCP 질문
WhatsApp Chat Reader MCP를 Claude Code에 추가하려면 어떻게 하나요?
터미널에서 claude mcp add wa-chat-reader -- uvx wa-chat-reader를 실행합니다. 모든 프로젝트에서 사용할 수 있게 하려면 --scope user를 추가합니다.
WhatsApp Chat Reader MCP를 Cursor에 추가하려면 어떻게 하나요?
~/.cursor/mcp.json를 열고 mcpServers 아래에 서버를 추가합니다. 위 설치 섹션에 표시된 Cursor 구성을 사용합니다.
WhatsApp Chat Reader MCP는 어떤 도구를 제공하나요?
2개 도구를 제공합니다. 예: get_whatsapp_messages, get_whatsapp_chat_list.
WhatsApp 데이터가 클라우드로 전송되나요?
아니요, 모든 작업은 로컬에서 실행되며 데이터는 컴퓨터 외부로 절대 전송되지 않습니다.
이 서버가 메시지를 수정하거나 삭제할 수 있나요?
아니요, 이 서버는 읽기 전용이며 쓰기, 수정 또는 삭제를 방지하는 SQLite 모드를 사용합니다.
macOS에서 사용하려면 어떤 권한이 필요한가요?
WhatsApp 데이터베이스가 보호된 그룹 컨테이너에 있으므로 시스템 설정에서 해당 프로세스에 전체 디스크 접근 권한을 부여해야 합니다.
AI가 얼마나 오래된 메시지까지 읽을 수 있나요?
조회 범위는 WHATSAPP_MAX_DAYS 변수에 의해 제한되며 기본값은 30일입니다.