WhatsApp MCP 서버(TypeScript/Baileys)

이는 TypeScript로 구축되고 @whiskeysockets/baileys 라이브러리를 사용하는 WhatsApp용 MCP(Model Context Protocol) 서버입니다.

이 기능을 사용하면 개인 WhatsApp 계정을 AI 에이전트(데스크톱 앱이나 Cursor를 통한 Anthropic Claude 등)에 연결하여 다음과 같은 작업을 수행할 수 있습니다.

• 개인 WhatsApp 메시지를 검색하세요.
• 연락처(개인, 그룹 아님)를 검색하세요.
• 최근 채팅을 나열하세요.
• 특정 채팅에 대한 메시지 기록을 검색합니다.
• 개인이나 그룹에 메시지를 보냅니다.

WhatsApp 웹 다중 기기 API를 사용하여 개인 WhatsApp 계정 에 직접 연결됩니다. 모든 메시지와 인증 정보는 SQLite 데이터베이스( ./data/ )와 인증 캐시( ./auth_info/ )에 로컬로 저장됩니다. 데이터는 연결된 AI 에이전트가 제공된 MCP 도구(에이전트 인터페이스를 통해 제어 가능)를 명시적으로 사용하는 경우에만 전송됩니다.

(선택 사항: 여기 참조 예시와 유사한 스크린샷이나 GIF를 추가하는 것을 고려하세요)

예

사용자: WhatsApp에서 "Meu amor"에게 "Te amo"라고 적힌 WhatsApp 메시지를 보내세요.

비서: 알겠습니다. 먼저 연락처를 찾아야 합니다. whatsapp.search_contacts 도구를 사용하세요.

지엑스피1

도구 결과:

도우미: 연락처를 찾았습니다. 지금 메시지를 보내고 있습니다. 다음 도구를 사용 중입니다: whatsapp.send_message

도구 결과:

주요 기능(MCP 도구)

서버는 연결된 AI 에이전트에 다음 도구를 제공합니다.

• search_contacts : 이름이나 전화번호 부분(JID)으로 연락처를 검색합니다.
• list_messages : 페이지별로 특정 채팅에 대한 메시지 기록을 검색합니다.
• list_chats : 채팅을 나열합니다. 활동이나 이름별로 정렬 가능하고, 필터링, 페이지 구분이 가능하며, 마지막 메시지 세부 정보가 선택적으로 포함됩니다.
• get_chat : 특정 채팅에 대한 자세한 정보를 가져옵니다.
• get_message_context : 특정 메시지 ID 바로 전과 직후에 보낸 메시지를 검색하여 컨텍스트를 파악합니다.
• send_message : 지정된 수신자 JID(사용자 또는 그룹)에게 문자 메시지를 보냅니다.

설치

필수 조건

• Node.js: 버전 23.10.0 이상( package.json 파일에 명시됨). node -v 명령어로 버전을 확인할 수 있습니다. (기본적으로 TypeScript 및 SQLite를 지원합니다.)
• npm (또는 yarn/pnpm): 일반적으로 Node.js와 함께 제공됩니다.
• AI 클라이언트: Anthropic Claude Desktop 앱, Cursor, Cline 또는 Roo Code(또는 다른 MCP 호환 클라이언트).

단계

1. 이 저장소를 복제하세요:
   git clone <your-repo-url> whatsapp-mcp-ts cd whatsapp-mcp-ts
2. 종속성 설치:
   npm install # or yarn install / pnpm install
3. 처음으로 서버를 실행합니다. node 사용하여 메인 스크립트를 직접 실행합니다.
   node src/main.ts
   • 처음 실행하면 quickchart.io 사용하여 QR 코드 링크를 생성하고 기본 브라우저에서 열려고 시도할 가능성이 높습니다.
   • WhatsApp 모바일 앱을 사용하여 이 QR 코드를 스캔하세요(설정 > 연결된 기기 > 기기 연결).
   • 인증 자격 증명은 auth_info/ 디렉토리에 로컬로 저장됩니다(git에서는 무시됩니다).
   • 메시지가 동기화되어 ./data/whatsapp.db 에 저장됩니다. 기록 크기에 따라 시간이 다소 걸릴 수 있습니다. wa-logs.txt 와 콘솔 출력에서 진행 상황을 확인하세요.
   • 이 터미널 창을 계속 실행하세요. 동기화가 완료되면 닫아도 됩니다.

AI 클라이언트 구성

AI 클라이언트에게 MCP 서버를 시작하는 방법을 알려줘야 합니다.

1. 구성 JSON을 준비하세요. 다음 JSON 구조를 복사하세요. {{PATH_TO_REPO}} 이 저장소를 복제한 디렉터리의 절대 경로 로 바꿔야 합니다.
   { "mcpServers": { "whatsapp": { "command": "node", "args": [ "{{PATH_TO_REPO}}/src/main.ts" ], "timeout": 15, // Optional: Adjust startup timeout if needed "disabled": false } } }
   • 절대 경로 가져오기: 터미널에서 whatsapp-mcp-ts 디렉터리로 이동하여 pwd 실행합니다. {{PATH_TO_REPO}} 명령에 이 출력을 사용합니다.
2. 구성 파일을 저장합니다.
   • Claude Desktop의 경우: JSON을 구성 디렉토리에 claude_desktop_config.json 으로 저장합니다.
     • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
     • Windows: %APPDATA%\Claude\claude_desktop_config.json (가능한 경로, 필요한 경우 확인)
     • Linux: ~/.config/Claude/claude_desktop_config.json (가능한 경로, 필요한 경우 확인)
   • 커서의 경우: JSON을 구성 디렉토리에 mcp.json 으로 저장합니다.
     • ~/.cursor/mcp.json
3. Claude Desktop/Cursor를 다시 시작하세요. AI 클라이언트를 닫았다가 다시 여세요. 이제 "WhatsApp" MCP 서버를 감지하여 해당 도구를 사용할 수 있습니다.

용법

서버가 실행되고( node src/main.ts 통해 수동으로 시작하거나 AI 클라이언트가 설정 파일을 통해 시작) AI 클라이언트에 연결되면 에이전트의 채팅 인터페이스를 통해 WhatsApp 데이터와 상호작용할 수 있습니다. 연락처 검색, 최근 채팅 목록 작성, 메시지 읽기 또는 전송을 요청하세요.

아키텍처 개요

이 애플리케이션은 다음을 수행하는 단일 Node.js 프로세스입니다.

1. @whiskeysockets/baileys 사용하여 WhatsApp 웹 API에 연결하고 인증 및 실시간 이벤트를 처리합니다.
2. node:sqlite 사용하여 WhatsApp 채팅과 메시지를 SQLite 데이터베이스( ./data/whatsapp.db )에 로컬로 저장합니다.
3. @modelcontextprotocol/sdk 사용하여 표준 입출력(stdio)을 통해 AI 클라이언트의 요청을 수신하는 MCP 서버를 실행합니다.
4. 로컬 SQLite 데이터베이스를 쿼리하거나 Baileys 소켓을 사용하여 메시지를 보내는 MCP 도구를 제공합니다.
5. 활동 로깅에는 pino 사용합니다(WhatsApp 이벤트의 경우 wa-logs.txt , MCP 서버 활동의 경우 mcp-logs.txt ).

데이터 저장 및 개인 정보 보호

• 인증: WhatsApp 연결 자격 증명은 ./auth_info/ 디렉토리에 로컬로 저장됩니다.
• 메시지 및 채팅: 메시지 기록과 채팅 메타데이터는 ./data/whatsapp.db SQLite 파일에 로컬로 저장됩니다.
• 로컬 데이터: auth_info/ 와 data/ 는 모두 .gitignore 에 포함되어 실수로 커밋되는 것을 방지합니다. 이 디렉터리는 민감한 디렉터리로 취급하세요.
• LLM 상호작용: AI 에이전트가 제공된 MCP 도구(예: list_messages , send_message ) 중 하나를 적극적으로 사용할 때만 연결된 대규모 언어 모델(LLM)로 데이터가 전송됩니다. 서버 자체는 다른 곳으로 데이터를 적극적으로 전송하지 않습니다.

기술적 세부 사항

• 언어: TypeScript
• 런타임: Node.js (>= v23.10.0)
• WhatsApp API: @whiskeysockets/baileys
• MCP SDK: @modelcontextprotocol/sdk
• 데이터베이스: node:sqlite (번들된 SQLite)
• 로깅: pino
• 스키마 검증: zod (MCP 도구 입력용)

문제 해결

• QR 코드 문제:
  • QR 코드 링크가 자동으로 열리지 않으면 콘솔 출력에서 quickchart.io URL을 확인하고 수동으로 열어보세요.
  • 휴대폰의 WhatsApp 앱으로 QR 코드를 즉시 스캔하세요.
• 인증 실패/로그아웃:
  • DisconnectReason.loggedOut 오류로 연결이 종료되면 재인증해야 합니다. 서버를 중지하고 ./auth_info/ 디렉터리를 삭제한 후 서버( node src/main.ts )를 다시 시작하여 새 QR 코드를 받으세요.
• 메시지 동기화 문제:
  • 초기 동기화에는 시간이 걸릴 수 있습니다. wa-logs.txt 에서 활동 내역을 확인하세요.
  • 메시지가 동기화되지 않았거나 누락된 것 같으면 전체 재설정이 필요할 수 있습니다. 서버를 중지하고 ./auth_info/ 및 ./data/ 디렉터리를 모두 삭제한 후 서버를 다시 시작하여 인증을 다시 수행하고 기록을 다시 동기화하세요.
• MCP 연결 문제(Claude/Cursor):
  • claude_desktop_config.json 또는 mcp.json 파일에서 command 과 args (특히 {{PATH_TO_REPO}} })를 다시 한번 확인하세요. 경로가 절대 경로이고 올바른지 확인하세요.
  • Node.js가 올바르게 설치되었고 시스템 PATH에 있는지 확인하세요.
  • MCP 서버 시작과 관련된 오류가 있는지 AI 클라이언트의 로그를 확인하세요.
  • MCP 관련 오류는 이 서버의 로그( mcp-logs.txt )에서 확인하세요.
• 메시지 전송 오류:
  • 수신자 JID가 올바른지 확인하세요(예: 사용자의 경우 number@s.whatsapp.net , 그룹의 경우 groupid@g.us ).
  • Baileys의 구체적인 오류는 wa-logs.txt 확인하세요.
• 일반 문제: 자세한 오류 메시지는 wa-logs.txt 와 mcp-logs.txt 에서 확인하세요.

추가적인 MCP 통합 문제에 대해서는 공식 MCP 문서를 참조하세요.

크레딧

• https://github.com/lharries/whatsapp-mcp 이 코드베이스와 동일한 작업을 수행하지만 go와 python을 사용합니다.

특허

이 프로젝트는 ISC 라이선스에 따라 라이선스가 부여되었습니다( package.json 참조).