finereli/whatsapp-mcp

A read-only MCP server that lets your AI agent search and read your own WhatsApp messages. Use it free at whatsapp.finereli.com, or run your own copy on Cloudflare.

무엇인가요

whatsapp-mcp는 AI 에이전트(예: Claude Code)가 사용자의 WhatsApp 채팅 내용을 읽고 검색할 수 있게 해주는 소규모 셀프 호스팅 서버입니다. Cloudflare Workers 서비스로 실행되며, Durable Object 내의 SQLite 데이터베이스에 메시지를 저장하고 에이전트가 호출할 수 있는 간단한 MCP(Message-Control-Protocol) 엔드포인트를 노출합니다.

작동 방식

연결 – WhatsApp Web에 기기를 추가하는 것과 마찬가지로 웹 UI에서 QR 코드를 스캔(또는 전화번호 방식 사용)합니다. 서버는 연결된 기기가 되어 WhatsApp이 새 기기에 제공하는 채팅 기록을 가져옵니다.
저장 – 모든 메시지, 채팅 메타데이터 및 전체 텍스트 검색 인덱스는 Durable Object 내의 SQLite DB에 보관됩니다. 데이터는 다른 곳으로 전송되지 않습니다.
가져오기 – 하루에 한 번(또는 필요 시) 서버가 WhatsApp에 다시 연결하여 마지막 가져오기 이후 도착한 새 메시지를 가져오고 DB를 업데이트한 후 연결을 끊습니다. 휴대폰은 정상적으로 작동합니다.
에이전트 액세스 – AI 에이전트는 MCP 도구 세트(채팅 목록, 메시지 가져오기, 검색 등)를 사용하여 /mcp 엔드포인트와 통신합니다. 서버는 먼저 DB가 최신 상태인지 확인하고(10분 이상 경과 시 가져오기 수행) 요청된 데이터를 반환합니다.

주요 기능 (MCP 도구)

도구	기능
`list_chats`	최근 활동순으로 채팅을 반환하며, 이름/번호 필터링을 지원합니다.
`get_messages`	날짜별 페이지네이션을 사용하여 단일 채팅에서 메시지를 검색합니다.
`search_messages`	모든 채팅 또는 특정 채팅 내에서 전체 텍스트 검색을 수행합니다.
`unnamed_chats`	전화번호만 있고 저장된 연락처 이름이 없는 채팅을 나열합니다.
`set_contact_names`	전화번호에 사용자 지정 이름을 저장합니다. 이 이름은 향후 쿼리에서 사용됩니다.
`sync_now`	새 WhatsApp 메시지를 즉시 가져오도록 강제합니다.
`link_status`	기기 연결 여부, 마지막 가져오기 시간, 저장소 크기를 표시합니다.
`relink`	기기 연결을 해제하여 새 QR 코드를 스캔할 수 있게 합니다. 기존 저장된 메시지는 유지됩니다.

설정 단계 (개요)

사전 요구 사항 – Workers 유료 플랜을 사용하는 Cloudflare 계정, Node 20+, WhatsApp이 설치된 휴대폰.
복제 및 설치 – git clone … && npm install.
KV 네임스페이스 생성 – npx wrangler kv namespace create OAUTH_KV를 실행하고 출력된 ID를 wrangler.jsonc에 붙여넣습니다.
비밀번호 설정 – npx wrangler secret put OWNER_PASSWORD (12자 이상).
배포 – npm run deploy. Wrangler가 https://whatsapp-mcp.your-name.workers.dev와 같은 URL을 출력합니다.
WhatsApp 연결 – URL을 열고 QR 코드를 스캔(또는 전화번호 옵션 사용)합니다. 첫 가져오기에는 시간이 걸릴 수 있습니다.
에이전트 연결 – Claude Code에서 claude mcp add --transport http whatsapp https://your-url/mcp를 실행한 다음 설정한 비밀번호로 /mcp 명령을 사용합니다.

중요한 제한 사항 및 위험

비공식 – WhatsApp Web과 동일한 리버스 엔지니어링 프로토콜(Baileys 라이브러리 경유)을 사용합니다. 이는 WhatsApp 서비스 약관을 위반하며, 읽기 전용 기기로서의 실질적인 위험은 낮지만 0은 아닙니다.
읽기 전용 – 메시지 전송 기능이 없습니다. 서버는 의도적으로 전송 API를 노출하지 않습니다.
단일 사용자 전용 – 각 배포는 하나의 WhatsApp 계정 및 소유자 비밀번호에 연결됩니다. 다중 사용자 지원을 위해서는 코드 수정이 필요합니다.
미디어 다운로드 불가 – 이미지, 음성 메모 등은 [image]와 같은 자리 표시자로 표시되며 가져오거나 전사되지 않습니다.
연락처 이름 – 저장되지 않은 연락처와의 채팅은 전화번호로 표시됩니다. 에이전트는 unnamed_chats를 호출한 후 set_contact_names를 호출하여 읽기 쉬운 이름을 지정해야 합니다.
Cloudflare 유료 플랜 – 대규모 기록을 가져오려면 더 높은 CPU 제한이 필요하며, 이는 유료 Workers 플랜에서만 제공됩니다.
잠재적 오류 – 서버가 리버스 엔지니어링된 프로토콜에 의존하므로 향후 WhatsApp 업데이트로 인해 작동이 중단될 수 있습니다.

권장 사용자

개인적인 맥락이 필요한 AI 어시스턴트를 구축하는 개발자 (예: "내 친구가 비행기에 대해 뭐라고 했지?").
데이터를 타사 서비스가 아닌 자신의 Cloudflare 계정에 보관하려는 개인정보 보호를 중시하는 사용자.
LLM 기반 개인 에이전트를 실험하는 연구자.

라이선스

MIT – 코드를 자유롭게 사용, 수정 및 배포할 수 있습니다.