whatsapp-mcp-plus

안전하고, 설정이 필요 없는 WhatsApp MCP 서버. 기본적으로 읽기 전용이며 안전합니다.

개인 WhatsApp을 MCP 클라이언트(Claude Desktop, Cursor, Claude Code)에 연결하여 AI가 WhatsApp을 검색, 읽기, 요약하고, 허용한 경우에만 작업을 수행할 수 있게 해주며, 계정을 안전하게 보호하는 가드레일을 제공합니다.

이 프로젝트는 (현재 중단된) lharries/whatsapp-mcp의 유지 관리되는 단일 바이너리 후속 버전으로, Baileys 기반 TypeScript로 재구축되었으며 이전에는 없었던 안전 계층이 추가되었습니다.

⚠️ 사용 전에 계정 안전 및 서비스 약관을 읽어보세요. 이 도구는 비공식 WhatsApp 클라이언트를 사용합니다. 부주의하게 사용하면 번호가 차단될 수 있습니다. 이 도구는 해당 위험을 최소화하도록 설계되었지만 완전히 제거할 수는 없습니다.

내 대화에서 만드는 WhatsApp Rewind

AI에게 whatsapp_rewind을 요청하면 대화 기록에서 Spotify Wrapped 스타일의 스토리 카드 세트(1080×1920 SVG)를 생성합니다. 커버, 주요 인물, 나의 일상 리듬, 인기 이모지, 답장 속도 리더보드, 숫자로 보는 통계:

단일 카드가 더 편한가요? wrapped_card는 공유 가능한 SVG 하나를 생성하고, whatsapp_wrapped는 터미널 카드를 출력합니다. 그 외에도: response_leaderboard(가장 빨리 답장하는 상대 / 가장 오래 읽지 않고 두는 상대), chat_stats(채팅별 통계, 답장 시간 포함), top_words, export_chat이 있습니다.

Related MCP server: WA MCP

원본 대신 이걸 사용해야 하는 이유

빠른 시작

npx whatsapp-mcp-plus

첫 실행 시 터미널에 QR 코드가 출력됩니다. 휴대폰에서 WhatsApp을 열고 → 설정 → 연결된 기기 → 기기 연결을 선택한 후 스캔하세요. 최근 대화 기록이 로컬 SQLite 데이터베이스로 동기화됩니다. AI가 도구 호출을 통해 명시적으로 읽는 것 외에는 어떤 데이터도 기기 밖으로 나가지 않습니다.

또는 Docker 사용 시(연결과 서버가 하나의 컨테이너에 포함):

docker build -t whatsapp-mcp-plus .
docker run -it -v wamcp-data:/app/data -v wamcp-auth:/app/auth_info whatsapp-mcp-plus

페어링 없이 분석 기능 확인하기

whatsapp_wrapped와 response_leaderboard가 무엇을 생성하는지 보고 싶으신가요? 데모를 실행하면 샘플 데이터베이스가 생성되고 실제 도구 출력이 표시됩니다:

npm run demo

MCP 클라이언트에 연결하기

{
  "mcpServers": {
    "whatsapp": {
      "command": "npx",
      "args": ["-y", "whatsapp-mcp-plus"],
      "env": { "WAMCP_MODE": "read-only" }
    }
  }
}

• Claude Desktop: claude_desktop_config.json

• Cursor: ~/.cursor/mcp.json

안전 모델(기본 안전)

WhatsApp 차단은 대부분 행동 기반입니다. 읽기는 위험이 낮고, 냉담하거나 대량으로 보내는 것은 위험이 높습니다. 기본값은 안전 구역에 머물도록 조정되어 있습니다.

모드(WAMCP_MODE):

• read-only (기본값) — 모든 쓰기 도구가 차단됩니다. 검색/읽기/분석만 가능합니다.

• assisted — 전송이 허용되지만 허용 목록 + 속도 제한 + 확인 절차로 제한됩니다.

• unrestricted — 제한 해제(옵트인, 권장하지 않음).

가드레일(unrestricted 외에는 기본 활성화):

• 허용 목록 — 기존 연락처 또는 먼저 메시지를 보낸 사람에게만 메시지를 보낼 수 있습니다(낯선 사람에게 메시지를 보내는 것이 차단의 1순위 원인). allowlist_add 도구로 연락처별로 재정의할 수 있습니다.

• 속도 제한 — 분당 + 일일 상한과 사람과 유사한 간격+지터가 전송 사이에 적용됩니다.

• 전송 전 확인 — 전송은 토큰을 반환하고 대기합니다. confirm_action을 호출하기 전에는 아무것도 전송되지 않습니다. 이는 프롬프트 인젝션 메시지가 발송되는 것을 방지합니다.

• 인젝션 가드 — AI를 대상으로 한 지시처럼 보이는 수신 메시지는 모델이 명령이 아닌 데이터로 취급하도록 플래그가 지정됩니다.

모든 설정은 환경 변수로 조정 가능합니다: WAMCP_ALLOWLIST_ONLY, WAMCP_REQUIRE_CONFIRM, WAMCP_RATE_PER_MINUTE, WAMCP_RATE_PER_DAY, WAMCP_MIN_GAP_MS, WAMCP_JITTER_MS.

도구

51개 도구(중단된 원본은 12개):

읽기: search_contacts, list_chats, list_groups, get_chat, list_messages(날짜 범위 지정 가능), get_last_interaction, contact_info, get_message_context, search_messages 전송: send_message(답장 포함), send_file, send_voice_note, send_location, send_poll, send_contact 메시지 작업: react_to_message, edit_message, delete_message, mark_read, forward_message, star_message 그룹: group_info, create_group, group_update_participants, group_set_subject, group_set_description, group_invite_link, group_leave 채팅 관리: pin_chat, mute_chat, block_contact, check_number_on_whatsapp, get_profile_picture 상태 / 프로필: send_presence, set_profile_status, set_profile_name 미디어 / 인텔리전스: download_media, transcribe_voice_message 분석: whatsapp_rewind(6장 스토리 카드 세트), wrapped_card(공유 가능한 단일 SVG), whatsapp_wrapped(터미널 카드), response_leaderboard(가장 빨리 답장하는 상대 / 가장 오래 읽지 않고 두는 상대), top_words, chat_stats(채팅별 통계, 응답 시간 포함), export_chat(마크다운/텍스트 대화 기록) 제어: get_status, get_me, set_mode, confirm_action, allowlist_add/remove/list

음성 전사

transcribe_voice_message는 음성 메모를 다운로드하고, WAMCP_TRANSCRIPTION_CMD(텍스트 전사를 출력하는 {input} 포함 명령)를 설정한 경우 선택한 STT(예: whisper)로 전사를 실행합니다. 설정하지 않으면 오디오가 다운로드되고 해당 경로만 반환됩니다.

설정 참조

계정 안전 및 서비스 약관

이 프로젝트는 비공식 WhatsApp Web 클라이언트인 Baileys를 사용합니다. 개인 WhatsApp 계정을 자동화하는 것은 WhatsApp 서비스 약관에 위배되며 번호가 일시적 또는 영구적으로 차단될 수 있습니다. 위험을 줄이려면:

• 정말로 전송이 필요하지 않다면 기본 읽기 전용 모드를 유지하세요.

• 콜드 아웃리치, 대량 발송, 동일/스팸 메시지에 절대 사용하지 마세요.

• 새 SIM보다는 오래되고 활발히 사용되는 번호를 선호하세요. VOIP 번호는 피하세요.

• 마케팅 도구가 아닌 개인 비서로 취급하세요.

이 도구를 사용함으로써 이 위험을 수락하는 것입니다. 이 도구는 있는 그대로 제공되며, 개인 및 교육 목적으로만 사용되며, 어떠한 보증도 없습니다. WhatsApp 또는 Meta와 제휴 관계가 아닙니다.

크레딧

whatsapp-mcp-ts(ISC) 및 whatsapp-mcp(MIT)에서 파생되었습니다. NOTICE를 참조하세요. MIT 라이선스.