Claude Desktop용 MCP Whatsapp

Claude Desktop이 WhatsApp 채팅 및 메시지 기록에 읽기 전용으로 액세스할 수 있게 해주는 Model Context Protocol (MCP) 서버입니다.

Baileys(WhatsApp Web 프로토콜)를 기반으로 구축되었으며, 전화번호, 비즈니스 API, 클라우드 서비스가 필요 없습니다. 모든 것이 로컬 머신에서 실행됩니다.

⚠️ 면책 조항 이는 비공식 통합입니다. WhatsApp은 승인되지 않은 클라이언트를 사용하는 계정을 해지할 수 있습니다. 기본 번호가 아닌 보조/테스트 번호를 사용하십시오. 작성자는 계정 정지에 대해 책임을 지지 않습니다.

✨ 기능

• 🔌 로컬 우선 — 외부 API 없음, 클라우드 없음

• 💾 SQLite 지속성 — 채팅 및 메시지가 로컬 DB에 저장됨

• 📚 기록 동기화 — 처음 페어링 시 기존 WhatsApp 기록 다운로드

• 🔎 채팅 검색 — 이름, 푸시 이름 또는 JID로 검색

• 📖 메시지 읽기 — 모든 채팅에서 메시지 읽기 (텍스트, 이미지 캡션, 미디어 메타데이터)

• 🧠 Claude 네이티브 — Claude Desktop에 평문으로 질문

Related MCP server: WhatsApp MCP Server

🔧 사용 가능한 MCP 도구

📦 사전 요구 사항

• Node.js 18+ — node --version으로 확인

• Claude Desktop (macOS 또는 Windows) — 다운로드

• QR 코드를 스캔할 수 있는 전화기가 있는 WhatsApp 계정

• macOS 또는 Linux 권장 (Windows는 경로 조정 시 작동)

🚀 설치

1. 저장소 복제

git clone https://github.com/danialadzhar/mcp-whatsapp.git
cd mcp-whatsapp

2. 의존성 설치

npm install

better-sqlite3 빌드에 실패하면 Xcode Command Line Tools(macOS)가 설치되어 있는지 확인하십시오: xcode-select --install

🔐 최초 설정 (WhatsApp 페어링 + 기록 동기화)

⚠️ 중요 — Claude Desktop을 구성하기 전에 이 작업을 수행하십시오. QR 코드는 setup.js를 통해 터미널에서만 표시될 수 있습니다. MCP 서버(Claude Desktop에 의해 실행됨)는 stdout이 MCP 프로토콜을 위해 예약되어 있으므로 QR을 표시할 수 없습니다. 이 단계를 건너뛰고 바로 Claude Desktop 구성으로 이동하면 봇이 페어링할 방법 없이 connecting 상태에서 멈추게 됩니다.

1. 설정 스크립트 실행

node setup.js

터미널에 QR 코드가 나타납니다.

2. 휴대폰에서 WhatsApp 열기

• 설정 → 연결된 기기 → 기기 연결로 이동

• "채팅 기록 포함" 또는 유사한 메시지가 표시되면 — 예를 선택하여 기록을 다운로드하십시오.

• 터미널의 QR 코드를 스캔하십시오.

3. 기록 다운로드 대기

터미널에 다음이 출력됩니다:

[HISTORY] chats=35 msgs=500 isLatest=false | batch #1 | DB: 35 chats, 500 messages
[HISTORY] chats=0 msgs=1200 isLatest=false | batch #2 | DB: 35 chats, 1700 messages
...

계정 크기에 따라 5-30분이 소요됩니다. 스크립트는 30초 동안 새로운 배치가 도착하지 않으면 완료된 것으로 자동 감지합니다.

4. 스크립트 중지

HISTORY SYNC COMPLETE 및 SAFE TO EXIT가 표시되면 Ctrl+C를 누르십시오.

⚙️ Claude Desktop 구성

⚠️ Claude Desktop Cowork / 예약된 작업과는 호환되지 않습니다. Cowork 또는 예약된 작업 기능이 활성화되면 Claude Desktop은 백그라운드 에이전트를 위해 여러 MCP 서버 인스턴스를 생성합니다. WhatsApp은 한 번에 하나의 활성 연결된 기기 연결만 허용하므로, 중복 인스턴스가 세션을 차지하려고 다투어 status=440, reconnect=true 루프를 발생시킵니다. 구성에서 둘 다 비활성화하십시오(아래 2단계 참조). 그렇지 않으면 이 통합이 안정적으로 작동하지 않습니다.

1. Claude Desktop 구성 파일 찾기

2. MCP 서버 추가

파일을 열고 mcpServers 섹션에 다음을 병합하십시오(키가 없으면 생성하십시오):

{
  "mcpServers": {
    "whatsapp": {
      "command": "/absolute/path/to/node",
      "args": [
        "/absolute/path/to/mcp-whatsapp/mcp-server.js"
      ]
    }
  }
}

실제 경로로 바꾸십시오:

• 노드 경로 가져오기: which node (macOS/Linux) 또는 where node (Windows)

• 절대 경로 사용 — Claude Desktop은 셸 PATH를 안정적으로 확인하지 않습니다.

예시 (macOS, Homebrew node), Cowork/예약된 작업 비활성화:

{
  "mcpServers": {
    "whatsapp": {
      "command": "/opt/homebrew/bin/node",
      "args": [
        "/Users/yourname/projects/mcp-whatsapp/mcp-server.js"
      ]
    }
  },
  "preferences": {
    "coworkScheduledTasksEnabled": false,
    "ccdScheduledTasksEnabled": false
  }
}

구성 파일에 이미 "preferences" 블록이 있는 경우, 두 개의 *ScheduledTasksEnabled 키를 추가하기만 하면 됩니다. 블록을 중복 생성하지 마십시오.

3. Claude Desktop 재시작

Cmd+Q로 완전히 종료(창만 닫지 마십시오)한 후 다시 여십시오.

4. 테스트

Claude Desktop 채팅에서 다음을 질문하십시오:

what is my whatsapp status

Claude가 whatsapp_status 도구를 호출합니다. 권한 프롬프트가 나타나면 승인하십시오.

💬 예시 프롬프트

연결되면 Claude Desktop에 다음과 같이 질문할 수 있습니다:

• "가장 최근 WhatsApp 채팅 10개 나열해줘"

• "WhatsApp에서 'Ahmad'와의 채팅 검색해줘"

• "60123456789@s.whatsapp.net과의 마지막 메시지 50개 요약해줘"

• "읽지 않은 WhatsApp 채팅이 몇 개야?"

• "각 그룹 채팅의 마지막 메시지 보여줘"

• "누군가 '회의'를 언급한 대화 찾아줘" (Claude가 목록 나열 + 읽기 작업을 연결합니다)

Claude는 질문에 따라 어떤 도구를 호출할지 결정합니다.

🐛 문제 해결

❌ Error: Cannot find module '@whiskeysockets/baileys'

의존성을 설치하지 않았습니다.

cd mcp-whatsapp
npm install

❌ 로그에 status=440, reconnect=true 루프 발생

두 프로세스가 동일한 WhatsApp 세션을 두고 다투고 있습니다. 일반적인 원인:

1. Claude Desktop이 중복 MCP 서버를 생성함 — claude_desktop_config.json에서 Cowork/예약된 작업을 비활성화하십시오:

   "preferences": {
     "coworkScheduledTasksEnabled": false,
     "ccdScheduledTasksEnabled": false
   }

2. 터미널 스크립트 + Claude Desktop이 동시에 실행 중 — 터미널 프로세스를 종료하십시오:

   ps aux | grep "mcp-whatsapp" | grep -v grep
   kill <PID>

3. 두 개의 Claude Desktop 인스턴스 — Cmd+Q로 완전히 종료하고 한 번만 다시 여십시오.

❌ setup.js 실행 시 QR 코드가 나타나지 않음

• 다른 Node 프로세스가 auth_info/를 잡고 있지 않은지 확인하십시오:

  ps aux | grep "mcp-whatsapp" | grep -v grep

• setup.js를 실행하기 전에 Claude Desktop을 완전히 종료(Cmd+Q)하십시오.

• auth_info/를 삭제하고 다시 시도하십시오:

  rm -rf auth_info
  node setup.js

❌ Claude Desktop에 도구가 나타나지 않음

1. 구성 JSON이 유효한지 확인하십시오:

   # macOS
   python3 -c "import json; json.load(open('$HOME/Library/Application Support/Claude/claude_desktop_config.json'))"

2. MCP 서버 로그를 확인하십시오:

   # macOS
   tail -50 ~/Library/Logs/Claude/mcp-server-whatsapp.log

3. 구성의 노드 경로가 올바른지 확인하십시오:

   which node

4. Claude Desktop을 완전히 종료하고 재시작하십시오 — 구성을 다시 로드하려면 전체 앱 재시작이 필요합니다.

❌ connectionState: "connecting" 상태가 계속됨

• 세션이 손상되었을 수 있습니다. 다시 페어링하여 수정하십시오:

  # 1. Quit Claude Desktop (Cmd+Q)
  # 2. Delete auth
  rm -rf auth_info whatsapp.db
  # 3. Re-run setup
  node setup.js
  # 4. Scan QR

❌ 설정 후 DB에 0 chats, 0 messages 표시

• QR 스캔 중 WhatsApp에서 "채팅 기록 포함" 프롬프트를 건너뛰었을 가능성이 높습니다.

• WhatsApp은 초기 페어링 중에만 기록 동기화를 제공합니다. 수정 방법:

  rm -rf auth_info whatsapp.db
  node setup.js

  휴대폰에서 메시지가 표시되면 이번에는 기록을 포함하도록 선택하십시오.

❌ 올바른 구성에도 기록 동기화가 시작되지 않음

• 일부 WhatsApp 버전은 기록 전송 프롬프트를 건너뜁니다. 해결 방법:

  • 휴대폰의 WhatsApp을 최신 버전으로 업데이트

  • 휴대폰에서: 설정 → 채팅 → 채팅 기록 전송 (사용 가능한 경우)

  • 앞으로는 새 메시지만 캡처된다는 점을 수용

❌ node-gyp / better-sqlite3 빌드 오류

• macOS: xcode-select --install

• Linux: sudo apt install build-essential python3

• Windows: windows-build-tools 또는 Visual Studio Build Tools 설치

❌ Claude Desktop이 도구를 호출할 때 권한 거부됨

각 도구가 처음 호출될 때 Claude Desktop이 승인을 요청합니다. 원활한 사용을 위해 **"이 작업에 대해 허용"**을 선택하십시오. Claude Desktop 설정에서 도구별로 권한을 설정할 수도 있습니다.

❓ FAQ

이 봇은 24/7 메시지를 캡처하나요?

아니요. MCP 서버는 Claude Desktop이 열려 있는 동안에만 실행됩니다. Claude Desktop이 종료되면 봇 연결이 끊어집니다.

하지만 WhatsApp은 전달되지 않은 메시지를 연결된 기기에 최대 약 14일 동안 대기시킵니다. Claude Desktop을 다시 열면 오프라인 메시지가 도착하여 DB에 저장됩니다.

진정한 24/7 캡처를 원하시면 별도의 백그라운드 데몬을 실행하십시오(이 저장소에는 포함되지 않음).

WhatsApp이 내 계정을 정지할까요?

모든 비공식 클라이언트에 위험이 존재합니다. 완화 방법:

• 가능하면 보조/테스트 번호 사용

• 스팸 전송 금지 (이 저장소는 읽기 전용이므로 위험이 낮음)

• 대량 마케팅용으로 사용 금지

이 MCP로 메시지를 보낼 수 있나요?

이 버전은 의도적으로 읽기 전용입니다(더 안전함). 전송 기능을 추가하려면 mcp-server.js에 whatsapp_send_message 도구를 추가하십시오. 하지만 주의하십시오. MCP로 트리거된 전송은 강력하며 프롬프트 인젝션에 의해 악용될 수 있습니다.

내 데이터는 어디에 저장되나요?

• auth_info/ — 세션 자격 증명 (비공개 유지, 공유/커밋 금지)

• whatsapp.db — 채팅 및 메시지가 포함된 SQLite (비공개 유지)

둘 다 gitignore 처리되어 있습니다.

어떻게 제거하나요?

# Quit Claude Desktop
# Remove MCP server entry from claude_desktop_config.json
# Delete the repo folder
rm -rf mcp-whatsapp

휴대폰에서: WhatsApp → 연결된 기기 → 이 기기 제거.

여러 MCP 서버가 동일한 WhatsApp 세션을 공유할 수 있나요?

아니요. WhatsApp은 연결된 기기 인증당 하나의 활성 연결만 허용합니다. 여러 MCP 인스턴스를 실행하면 status=440 충돌 루프가 발생합니다.

그룹은 어떻게 되나요?

그룹 채팅이 지원됩니다. 다른 채팅과 마찬가지로 나열되고 읽을 수 있습니다. JID는 @g.us로 끝납니다.

🛠 알려진 제한 사항

• Claude Desktop Cowork / 예약된 작업과 호환되지 않음 — 이러한 기능은 단일 세션 WhatsApp 연결을 끊는 중복 MCP 인스턴스를 생성합니다. 비활성화해야 합니다(Claude Desktop 구성 참조).

• Claude Desktop이 열려 있는 동안에만 실행됨 — 24/7 캡처를 위해서는 별도의 데몬이 필요합니다(포함되지 않음).

• 미디어(이미지, 비디오, 오디오)는 다운로드되지 않음 — 텍스트 + 메타데이터만 가능.

• 반응은 부모 메시지에 연결되지 않고 별도의 메시지로 추적됨.

• 삭제된 메시지는 캡처되지 않음.

• 기록 동기화 양은 WhatsApp에 따라 다름 — 일반적으로 최근 6개월.

• macOS/Linux 테스트 완료; Windows 경로는 구성에서 조정 필요.

• 다중 계정 / 다중 테넌트용으로 설계되지 않음.

🤝 기여

이슈 및 PR 환영합니다. 다음을 준수하십시오:

• 로그와 함께 이슈 제기 (개인 정보 삭제)

• PR은 하나의 기능/수정 사항으로 제한

• 신중한 안전 설계(권한 게이트, 속도 제한, 확인 UX) 없이 send_message 추가 금지

📄 라이선스

MIT © Danial Adzhar

🙏 크레딧

• Baileys — 리버스 엔지니어링된 WhatsApp Web 클라이언트

• Model Context Protocol — Anthropic 표준

• better-sqlite3 — 빠른 동기식 SQLite