macOS용 WhatsApp MCP

Claude를 WhatsApp에 연결하는 Model Context Protocol 서버입니다. 자연스러운 대화를 통해 메시지를 읽고, 연락처를 검색하고, 답장을 보낼 수 있습니다.

기능

• 연락처 검색 — 이름이나 전화번호로 누구든 찾기

• 메시지 읽기 — 날짜 필터링 및 검색을 통해 채팅 기록 가져오기

• 채팅 목록 확인 — 읽지 않은 메시지 수를 포함한 최근 대화 보기

• 메시지 보내기 — Claude를 통해 직접 답장하기 (QR 인증 필요)

• 실시간 수신 — 메시지 도착 시 즉시 확인

요구 사항

• macOS (WhatsApp 데스크톱 앱이 설치 및 로그인되어 있어야 함)

• Python 3.10+

• Node.js 18+ (메시지 전송용)

설치

pip 사용

pip install whatsapp-mcp-macos

소스에서 설치

git clone https://github.com/kalki-kgp/whatsapp-mcp.git
cd whatsapp-mcp
pip install -e .

Claude Desktop에 연결

1. 설정 파일 열기:

   open ~/Library/Application\ Support/Claude/claude_desktop_config.json

   파일이 없으면 생성하세요.

2. WhatsApp MCP 서버 추가:

   {
     "mcpServers": {
       "whatsapp": {
         "command": "python3",
         "args": ["-m", "whatsapp_mcp"]
       }
     }
   }

3. Claude Desktop 재시작 (Cmd+Q 후 다시 열기)

4. 채팅 입력창의 MCP 도구 아이콘(🔨)을 확인하고 클릭하여 "whatsapp"이 나열되어 있는지 확인하세요.

5. 대화 시작:

   • "최근 WhatsApp 채팅 보여줘"

   • "저녁 약속 관련 메시지 검색해줘"

Cursor에 연결

프로젝트의 .cursor/mcp.json에 추가하세요:

{
  "mcpServers": {
    "whatsapp": {
      "command": "python3",
      "args": ["-m", "whatsapp_mcp"]
    }
  }
}

Cursor를 재시작하고 AI 채팅에서 WhatsApp 도구를 사용하세요.

사용법

메시지 읽기 (즉시 사용 가능)

Claude에게 다음과 같이 요청하세요:

• "최근 WhatsApp 채팅 보여줘"

• "저녁 식사에 관한 메시지 검색해줘"

• "어제 John이 뭐라고 했어?"

• "읽지 않은 메시지 요약해줘"

메시지 보내기 (브리지 필요)

1. WhatsApp 브리지 시작:

   cd bridge && npm install && npm start

2. Claude에게 연결 상태 확인 요청:

   • "WhatsApp 상태 확인해줘"

3. QR 코드가 표시되면 브라우저에서 데이터 URL을 열고 휴대폰으로 스캔하세요.

4. 연결되면 다음과 같이 보낼 수 있습니다:

   • "Mom에게 늦을 거라고 메시지 보내줘"

   • "John에게 '좋아요'라고 답장해줘"

도구

작동 원리

Claude ──MCP──▶ WhatsApp MCP Server
                       │
                       ├──▶ Local SQLite DBs (read messages)
                       │    ~/Library/Group Containers/group.net.whatsapp.WhatsApp.shared/
                       │
                       └──▶ WhatsApp Bridge (:3010) ──▶ WhatsApp Web
                            (for sending)

읽기 작업은 로컬 WhatsApp 데이터베이스를 직접 쿼리하므로 빠르고 오프라인에서도 작동합니다.

보내기 작업은 Baileys를 사용하여 WhatsApp Web에 연결하는 브리지를 통해 수행됩니다.

개발

# Clone
git clone https://github.com/kalki-kgp/whatsapp-mcp.git
cd whatsapp-mcp

# Install in dev mode
pip install -e ".[dev]"

# Run server
python -m whatsapp_mcp

개인정보 보호

• 모든 데이터는 로컬에 유지됩니다. 메시지는 사용자의 WhatsApp 데이터베이스에서 직접 읽습니다.

• 외부 서버로 데이터가 전송되지 않습니다 (메시지 전송 시 WhatsApp Web 제외).

• MCP 서버는 사용자의 컴퓨터에서 로컬로 실행됩니다.

라이선스

MIT