lharries/whatsapp-mcp

이것은 WhatsApp을 위한 Model Context Protocol (MCP) 서버입니다.

이를 통해 개인 WhatsApp 메시지(이미지, 비디오, 문서 및 오디오 메시지 포함)를 검색하고 읽을 수 있으며, 연락처를 검색하고 개인 또는 그룹에 메시지를 보낼 수 있습니다. 또한 이미지, 비디오, 문서 및 오디오 메시지를 포함한 미디어 파일을 보낼 수도 있습니다.

이 서버는 whatsmeow 라이브러리를 사용하는 WhatsApp Web 멀티 디바이스 API를 통해 사용자의 개인 WhatsApp 계정에 직접 연결됩니다. 모든 메시지는 SQLite 데이터베이스에 로컬로 저장되며, 에이전트가 도구(사용자가 제어함)를 통해 메시지에 접근할 때만 LLM(예: Claude)으로 전송됩니다.

다음은 Claude에 연결되었을 때 할 수 있는 작업의 예시입니다.

제가 작업하는 이 프로젝트 및 다른 프로젝트에 대한 업데이트를 받으려면 여기에 이메일을 입력하세요.

주의: 많은 MCP 서버와 마찬가지로, WhatsApp MCP는 치명적인 3요소(lethal trifecta)의 영향을 받을 수 있습니다. 이는 프로젝트 주입(project injection)이 개인 데이터 유출(private data exfiltration)로 이어질 수 있음을 의미합니다.

• Go

• Python 3.6+

• Anthropic Claude Desktop 앱 (또는 Cursor)

• UV (Python 패키지 관리자), 다음 명령어로 설치: curl -LsSf https://astral.sh/uv/install.sh | sh

• FFmpeg (선택 사항) - 오디오 메시지에만 필요합니다. 오디오 파일을 재생 가능한 WhatsApp 음성 메시지로 보내려면 반드시 .ogg Opus 형식이어야 합니다. FFmpeg가 설치되어 있으면 MCP 서버가 Opus 형식이 아닌 오디오 파일을 자동으로 변환합니다. FFmpeg가 없어도 send_file 도구를 사용하여 원본 오디오 파일을 보낼 수 있습니다.

• 이 저장소 복제 (Clone this repository): git clone https://github.com/lharries/whatsapp-mcp.git cd whatsapp-mcp

• WhatsApp 브리지 실행: whatsapp-bridge 디렉토리로 이동하여 Go 애플리케이션을 실행합니다:

cd whatsapp-bridge go run main.go

처음 실행할 때 QR 코드를 스캔하라는 메시지가 표시됩니다. WhatsApp 모바일 앱으로 QR 코드를 스캔하여 인증하세요.

약 20일 후에 다시 인증해야 할 수도 있습니다.

• MCP 서버에 연결: 적절한 {{PATH}} 값이 포함된 아래 JSON을 복사하세요:

{ "mcpServers": { "whatsapp": { "command": "{{PATH_TO_UV}}", // which uv를 실행하고 그 출력값을 여기에 입력하세요 "args": [ "--directory", "{{PATH_TO_SRC}}/whatsapp-mcp/whatsapp-mcp-server", // 리포지토리로 이동하여 pwd를 실행하고 그 출력값을 여기에 입력하세요 + "/whatsapp-mcp-server" "run", "main.py" ] } } }

Claude의 경우, 이 내용을 다음의 Claude Desktop 설정 디렉토리에 claude_desktop_config.json이라는 이름으로 저장하세요:
~/Library/Application Support/Claude/claude_desktop_config.json

Cursor의 경우, 이 내용을 다음의 Cursor 설정 디렉토리에 mcp.json이라는 이름으로 저장하세요:
~/.cursor/mcp.json

Claude Desktop / Cursor 재시작
Claude Desktop을 열면 이제 WhatsApp을 사용 가능한 통합 기능으로 볼 수 있습니다.

또는 Cursor를 재시작하세요.

Windows에서 이 프로젝트를 실행하는 경우, go-sqlite3가 제대로 컴파일되고 작동하려면 **CGO가 활성화(enabled)**되어 있어야 함을 유의하세요. 기본적으로 **Windows에서는 CGO가 비활성화(disabled)**되어 있으므로, 명시적으로 활성화하고 C 컴파일러(C compiler)를 설치해야 합니다.

C 컴파일러 설치

Windows용 C 컴파일러를 설치하기 위해 MSYS2를 사용하는 것을 권장합니다. MSYS2를 설치한 후, ucrt64\bin 폴더를 PATH에 반드시 추가하세요.

→ 단계별 가이드는 [여기]에서 확인할 수 있습니다.

CGO 활성화 및 앱 실행
cd whatsapp-bridge go env -w CGO_ENABLED=1 go run main.go

이 설정을 하지 않으면 다음과 같은 오류가 발생할 가능성이 높습니다:

Binary was compiled with 'CGO_ENABLED=0', go-sqlite3 requires cgo to work.

이 애플리케이션은 두 가지 주요 구성 요소로 이루어져 있습니다:

Go WhatsApp Bridge(whatsapp-bridge/): WhatsApp의 웹 API에 연결하고, QR 코드를 통해 인증을 처리하며, 메시지 기록을 SQLite에 저장하는 Go 애플리케이션입니다. WhatsApp과 MCP 서버 사이의 브리지(bridge) 역할을 합니다.

Python MCP Server(whatsapp-mcp-server/): Model Context Protocol (MCP)을 구현하는 Python 서버로, Claude가 WhatsApp 데이터와 상호작용하고 메시지를 송수신할 수 있도록 표준화된 도구(tools)를 제공합니다.

• 모든 메시지 기록은 whatsapp-bridge/store/ 디렉토리 내의 SQLite 데이터베이스에 저장됩니다.
• 데이터베이스는 채팅(chats) 및 메시지(messages)를 위한 테이블을 유지합니다.
• 메시지는 효율적인 검색 및 검색(retrieval)을 위해 인덱싱됩니다.

연결되면 Claude의 AI 기능을 WhatsApp 대화에 활용하여 Claude를 통해 WhatsApp 연락처와 상호작용할 수 있습니다.

Claude는 WhatsApp과 상호작용하기 위해 다음 도구(tools)를 사용할 수 있습니다:

search_contacts: 이름 또는 전화번호로 연락처 검색
list_messages: 선택적 필터 및 컨텍스트를 사용하여 메시지 검색
list_chats: 메타데이터와 함께 사용 가능한 채팅 목록 표시
get_chat: 특정 채팅에 대한 정보 가져오기
get_direct_chat_by_contact: 특정 연락처와의 직접 채팅 찾기
get_contact_chats: 특정 연락처가 포함된 모든 채팅 목록 표시
get_last_interaction: 특정 연락처와의 가장 최근 메시지 가져오기
get_message_context: 특정 메시지 주변의 컨텍스트 검색
send_message: 지정된 전화번호 또는 그룹 JID로 WhatsApp 메시지 전송
send_file: 지정된 수신자에게 파일(이미지, 비디오, 원시 오디오, 문서) 전송
send_audio_message: 오디오 파일을 WhatsApp 음성 메시지로 전송 (.ogg opus 파일이어야 하거나 ffmpeg가 설치되어 있어야 함)
download_media: WhatsApp 메시지에서 미디어를 다운로드하고 로컬 파일 경로 가져오기

MCP 서버는 다양한 미디어 유형의 송신 및 수신을 모두 지원합니다:

WhatsApp 연락처로 다양한 미디어 유형을 보낼 수 있습니다:

이미지, 비디오, 문서: send_file 도구를 사용하여 지원되는 모든 미디어 유형을 공유합니다.
음성 메시지: send_audio_message 도구를 사용하여 오디오 파일을 재생 가능한 WhatsApp 음성 메시지로 전송합니다.

• 최적의 호환성을 위해 오디오 파일은 .ogg Opus 형식이어야 합니다.
• FFmpeg가 설치되어 있으면 시스템이 다른 오디오 형식(MP3, WAV 등)을 필요한 형식으로 자동 변환합니다.
• FFmpeg가 없어도 send_file을 사용하여 원시 오디오 파일을 보낼 수 있습니다.

도구(tool)이지만, 재생 가능한 음성 메시지로 나타나지는 않습니다.

• 최적의 호환성을 위해 오디오 파일은 다음 형식이어야 합니다:

기본적으로 미디어의 메타데이터만 로컬 데이터베이스(local database)에 저장됩니다. 메시지에는 미디어가 전송되었다는 표시가 나타납니다. 이 미디어에 접근하려면 message_id와 chat_jid(미디어를 포함하는 메시지를 출력할 때 표시됨)를 인자로 받는 download_media 도구를 사용해야 합니다. 이 도구는 미디어를 다운로드한 후 파일 경로를 반환하며, 해당 경로는 파일을 열거나 다른 도구로 전달할 수 있습니다.

• Claude가 Python MCP 서버로 요청을 보냅니다.

• MCP 서버가 WhatsApp 데이터를 가져오기 위해 Go 브리지(bridge)에 쿼리하거나 SQLite 데이터베이스에 직접 쿼리합니다.

• Go 브리지는 WhatsApp API에 접근하여 SQLite 데이터베이스를 최신 상태로 유지합니다.

• 데이터는 체인을 통해 다시 Claude로 흐릅니다.

• 메시지를 보낼 때는 요청이 Claude에서 MCP 서버를 거쳐 Go 브리지로, 그리고 WhatsApp으로 흐릅니다.

• uv를 실행할 때 권한 문제가 발생하면, PATH에 추가하거나 실행 파일의 전체 경로를 사용해야 할 수도 있습니다.

• 통합 기능이 제대로 작동하려면 Go 애플리케이션과 Python 서버가 모두 실행 중인지 확인하십시오.

QR 코드 미표시: QR 코드가 나타나지 않으면 인증 스크립트를 다시 시작해 보세요. 문제가 지속되면 터미널이 QR 코드 표시를 지원하는지 확인하십시오. WhatsApp 이미 로그인됨: 세션이 이미 활성화되어 있는 경우, Go 브리지는 QR 코드를 표시하지 않고 자동으로 재연결됩니다. 기기 제한 도달: WhatsApp은 연결된 기기 수를 제한합니다. 이 제한에 도달하면 휴대폰의 WhatsApp(설정 > 연결된 기기)에서 기존 기기를 제거해야 합니다. 메시지 로드 안 됨: 초기 인증 후, 특히 채팅 내용이 많은 경우 메시지 기록이 로드되는 데 몇 분이 걸릴 수 있습니다. WhatsApp 동기화 오류: WhatsApp 메시지가 브리지와 동기화되지 않는 경우, 두 데이터베이스 파일(whatsapp-bridge/store/messages.db 및 whatsapp-bridge/store/whatsapp.db)을 삭제하십시오.

) 및 브릿지 (bridge)를 재시작하여 다시 인증하십시오.

Claude Desktop 통합과 관련한 추가적인 문제 해결 방법은 MCP 문서를 참조하십시오. 해당 문서에는 로그를 확인하고 일반적인 문제를 해결하는 데 도움이 되는 유용한 팁들이 포함되어 있습니다.