Cloudflare Workers에서 WhatsApp MCP – 읽기 전용 AI 기반 메시지 액세스

TL;DR – WhatsApp MCP가 하는 일과 중요한 이유

WhatsApp MCP는 Cloudflare Workers에서 실행되는 자체 호스팅, 읽기 전용 서버로, AI 에이전트(예: Claude Code)가 메시지를 보내지 않고도 자신의 WhatsApp 채팅을 검색하고 읽을 수 있게 합니다. 메시지를 Durable Object 내부의 개인 SQLite 데이터베이스에 저장하여 데이터를 사용자 통제 하에 유지하면서 표준 MCP 인터페이스를 노출합니다.

핵심 기능 – AI 에이전트가 채팅 기록을 조회할 수 있습니다

검색 및 읽기: 에이전트는 모든 채팅 또는 특정 대화에서 search_messages를 실행하고, get_messages로 채팅을 페이지 단위로 읽을 수 있습니다.
채팅 검색: list_chats는 최근 채팅을 반환하며, 이름이나 번호로 선택적으로 필터링할 수 있습니다.
이름 지정 지원: unnamed_chats는 전화번호만 있는 채팅을 표시하고, 에이전트는 set_contact_names를 호출하여 사람이 읽을 수 있는 이름을 연결할 수 있습니다.
주문형 동기화: sync_now는 저장된 복사본이 10분보다 오래된 경우 WhatsApp에서 즉시 가져오기를 강제합니다.
읽기 전용 보장: 서버는 메시지를 절대 보내지 않으며, 연결된 기기에 WhatsApp이 제공하는 것만 읽습니다.

아키텍처 – 시스템이 어떻게 비공개적이고 가벼운지

Durable Object를 단일 진실 소스로 사용: 모든 메시지, 연락처 및 Baileys 인증 데이터는 하나의 Durable Object(WhatsAppStore) 내부의 SQLite DB에 저장됩니다.
상태 비저장 Cloudflare Worker: Worker는 HTTP/MCP 라우팅, OAuth 및 매일 풀을 트리거하는 일일 cron을 처리합니다. 자체적으로 메시지 데이터를 보유하지 않습니다.
Baileys 라이브러리: 오픈 소스 WhatsApp Web 클라이언트 라이브러리를 사용하여 연결된 기기를 에뮬레이션합니다. 코드에는 Baileys가 Cloudflare의 workerd 런타임에서 실행되도록 하는 세 개의 shim(ws-shim.ts, vendor-bridge.mjs, polyfills.ts)이 포함되어 있습니다.
OAuth 보호: 비밀번호(OWNER_PASSWORD) 또는 선택적 이메일 기반 로그인이 /mcp 엔드포인트를 보호합니다. 토큰은 KV 네임스페이스(OAUTH_KV)에 저장됩니다.
외부 저장소 없음: OAuth 토큰용 Cloudflare KV를 제외하고 모든 데이터는 Durable Object 내에 유지됩니다. 제3자 저장소로 전송되는 것은 없습니다.

배포 단계 – 0에서 작동하는 엔드포인트까지

사전 요구 사항: Workers 유료 플랜의 Cloudflare 계정, Node 20+, WhatsApp이 설치된 휴대폰.

클론 및 설치:

git clone https://github.com/finereli/whatsapp-mcp
cd whatsapp-mcp
npm install

OAuth 토큰용 KV 네임스페이스 생성:
```
npx wrangler kv namespace create OAUTH_KV
```
강력한 소유자 비밀번호 설정 (12자 이상):
```
npx wrangler secret put OWNER_PASSWORD
```
배포:
```
npm run deploy
```
Wrangler는 https://whatsapp-mcp.<your-name>.workers.dev와 같은 URL을 출력합니다.
WhatsApp 연결: URL을 열고 WhatsApp → 설정 → 연결된 기기에서 QR 코드를 스캔합니다. 첫 번째 연결은 WhatsApp이 제공하는 모든 기록을 가져옵니다.
MCP 클라이언트 연결 (예: Claude Code):
```
claude mcp add --transport http whatsapp https://<your-url>/mcp
```
그런 다음 /mcp를 실행하고 비밀번호로 로그인합니다.

운영 참고 사항 – 프로젝트를 사용하거나 수정하기 전에 알아야 할 사항

서비스 약관 위험: 프로젝트는 WhatsApp Web과 동일한 역공학 프로토콜을 사용하므로 WhatsApp의 TOS에 위배됩니다. 읽기 전용 연결 기기의 경우 실질적인 위험은 낮지만 0은 아닙니다.
가져오기 제한: 초기 기록 가져오기는 Workers의 기본 CPU 한도를 초과할 수 있습니다. 저장소의 wrangler.jsonc는 한도를 높이며, 유료 플랜이 필요합니다.
데이터 완전성: WhatsApp은 새 기기에 적합하다고 판단하는 기록 부분만 보냅니다. 공백을 채우려면 기기를 다시 연결해야 합니다.
이름 없는 채팅: 많은 일회성 연락처가 전화번호로만 표시됩니다. 에이전트는 unnamed_chats를 호출한 다음 자체 연락처 저장소의 데이터로 set_contact_names를 호출하여 이를 해결할 수 있습니다.
미디어 처리: 미디어 파일은 다운로드되지 않으며 [image] 또는 [voice note 12s]와 같은 자리 표시자로 표시됩니다.
단일 사용자 설계: 각 배포는 하나의 WhatsApp 계정에 연결됩니다. 다중 사용자 지원은 Durable Object 키 지정을 재설계해야 합니다.

서버 확장 – 도구 추가 또는 인증 변경

새 MCP 도구 추가: src/mcp.ts에 등록하고 src/store.ts에서 필요한 SQL을 구현합니다. 읽기 전용 도구는 멱등하게 유지하세요.
인증 모드 전환: src/auth.ts는 비밀번호 또는 이메일 기반 로그인을 지원합니다. 다른 ID 공급자를 추가하려면 새 모드와 콜백 경로만 필요하며, 나머지 코드는 불투명한 베어러 토큰을 봅니다.
다중 사용자 확장: 고정 Durable Object 이름(owner)을 로그인한 ID에서 파생된 사용자별 식별자로 바꾸고 OAuth 페이로드를 조정합니다.
사용자 지정 이름 수집: { jid, name } 행을 생성할 수 있는 모든 외부 프로세스는 store.setCustomNames를 호출할 수 있습니다. 이를 통해 자격 증명을 서버에 노출하지 않고 CSV 업로드, CardDAV 동기화 또는 예약 작업이 가능합니다.
메시지 보내기: 프로젝트는 의도적으로 쓰기 기능을 생략합니다. 추가하려면 연결된 기기가 완전한 기능의 봇으로 바뀌어 계정 차단 위험이 증가하므로 신중한 보안 검토가 필요합니다.

디버깅 및 테스트 – 내장 진단 기능

선택적 PIN 비밀번호가 설정된 경우 다음 엔드포인트는 JSON을 반환합니다 (헤더 x-pin: <PIN> 포함):

/debug – 세션 단계, 연결 상태 및 최근 이벤트 표시.
/debug/pull – 즉시 가져오기 강제.
/debug/* – 다양한 읽기 전용 쿼리 (chats, messages, search, unnamed, sql).
/debug/logout – relink와 동일한 흐름 트리거.

로컬 개발은 npm run dev와 OWNER_PASSWORD가 포함된 .dev.vars 파일로 실행할 수 있습니다. 이렇게 하면 빈 저장소로 로컬 Durable Object가 생성되어 프로덕션 배포에 영향을 주지 않고 QR 페어링 흐름을 테스트할 수 있습니다.

커뮤니티 반응 – Hacker News 토론 하이라이트

"AI가 제 Android 게이트웨이를 만들어 문자 메시지를 보내고 읽을 수 있게 했습니다... 소프트웨어가 구축된 후에는 제로 SaaS, 제3자, 또는 구매가 없습니다." – @pizzafeelsright

"저를 괴롭히는 것은 대화의 상대방을 제3자 AI 회사에 노출하는 것입니다... 메시지를 주고받는 사람들은 결코 동의하지 않았습니다." – @SchemaLoad

"WhatsApp 웹 해킹을 실험해봤는데 때때로 차단당합니다. WA가 보편적인 연락 채널이라면 불편합니다." – @taldo

"무료 플랜으로는 충분하지 않을 것 같습니다. 저장소는 초기 가져오기에 유료 플랜이 필요하다고 언급합니다." – @calmingsolitude

"보조 기기를 연결한 후 차단되었습니다. WhatsApp은 비공식 연결 기기를 추가하는 계정을 영구적으로 차단할 수 있습니다." – @lgleason

이러한 댓글은 비공식 WhatsApp 통합에 수반되는 개인정보, 법적 및 안정성 문제를 강조합니다.

결론

WhatsApp MCP는 개인용 읽기 전용 AI 어시스턴트를 데이터를 외부에 저장하지 않고 Cloudflare Workers 위에 구축할 수 있음을 보여줍니다. MCP 프로토콜, Baileys 및 Cloudflare Durable Objects를 결합하여 AI 에이전트에게 자신의 메시지에 대한 상황별 액세스를 제공하는 구체적인 예를 제공하며, 역공학된 WhatsApp 통합의 법적 및 운영상의 트레이드오프도 함께 표면화합니다.