MCP WhatsApp 웹(TypeScript)

TypeScript로 구현된 WhatsApp 웹용 모델 컨텍스트 프로토콜(MCP) 서버입니다. 이 프로젝트는 기존 whatsapp-mcp 저장소를 TypeScript로 포팅한 것입니다.

이 MCP 서버를 사용하면 다음을 수행할 수 있습니다.

개인 WhatsApp 메시지(미디어 포함)를 검색하고 읽어보세요.
연락처 검색
개인이나 그룹에 메시지를 보내세요
미디어 파일(이미지, 비디오, 문서, 오디오)을 보내고 받습니다.

특징

TypeScript 구현 : 더 나은 개발자 경험과 코드 안정성을 위한 완전한 형식의 코드베이스
WhatsApp 웹 통합 : WhatsApp 웹에 직접 연결하기 위해 whatsapp-web.js를 사용합니다.
MCP 서버 : AI 어시스턴트와의 원활한 통합을 위한 모델 컨텍스트 프로토콜을 구현합니다.
미디어 지원 : 이미지, 비디오, 문서 및 오디오 메시지 보내기 및 받기
다양한 전송 옵션 : 유연한 통합을 위해 stdio 및 SSE 전송을 모두 지원합니다.

건축학

이 MCP 서버는 다음으로 구성됩니다.

TypeScript MCP 서버 : AI 어시스턴트가 WhatsApp과 상호 작용할 수 있도록 표준화된 도구를 제공하기 위해 모델 컨텍스트 프로토콜을 구현합니다.
WhatsApp 웹 서비스 : whatsapp-web.js를 통해 WhatsApp 웹에 연결하고, 인증을 처리하고, 메시지 전송/수신을 관리합니다.
도구 구현 : 연락처, 채팅, 메시지, 미디어 및 인증을 위한 다양한 도구를 제공합니다.

필수 조건

노드.js >= 18.0.0
npm 또는 yarn
Chrome/Chromium(Puppeteer에서 WhatsApp 웹 연결에 사용됨)
FFmpeg(선택 사항, 오디오 메시지 변환용)

설치

수동 설치

이 저장소를 복제하세요지엑스피1
종속성 설치
npm install
프로젝트를 빌드하세요
npm run build
환경 변수 구성(선택 사항)예제 환경 파일을 복사하고 필요에 따라 수정합니다.
cp .env.example .env
필요한 경우 로깅 수준을 조정하고 FFmpeg 경로를 지정할 수 있습니다.

FLUJO를 사용한 설치

FLUJO는 간소화된 설치 프로세스를 제공합니다.

FLUJO의 MCP 섹션으로 이동
"서버 추가"를 클릭하세요
이 GitHub 저장소 URL을 복사하여 붙여넣으세요: https://github.com/mario-andreschak/mcp-whatsapp-web
"구문 분석", "복제", "설치", "빌드" 및 "서버 업데이트"를 클릭합니다.

FLUJO는 자동으로 복제, 종속성 설치, 빌드 프로세스를 처리합니다.

용법

MCP 서버 시작

npm start

이렇게 하면 기본적으로 stdio 전송을 사용하여 MCP 서버가 시작되므로 Claude Desktop이나 유사한 애플리케이션과 통합하는 데 적합합니다.

중요: 서버를 처음 시작한 후에는 get_qr_code 도구를 사용하여 WhatsApp으로 인증하고 휴대폰으로 QR 코드를 스캔해야 합니다. 자세한 내용은 인증 섹션을 참조하세요.

개발 모드

npm run dev

이렇게 하면 TypeScript 감시 모드와 자동 서버 재시작 기능을 갖춘 개발 모드로 서버가 시작됩니다.

MCP Inspector를 사용한 디버깅

npm run debug

MCP 서버 테스트 및 디버깅을 위한 웹 인터페이스를 제공하는 MCP Inspector 도구가 실행됩니다. 이 도구를 사용하면 다음 작업을 수행할 수 있습니다.

사용 가능한 모든 도구와 해당 스키마 보기
도구를 직접 실행하고 응답을 확인하세요
AI 어시스턴트에 연결하지 않고도 서버를 테스트하세요
디버그 도구 실행 및 응답 검사

Claude Desktop에 연결

Claude Desktop에 대한 구성 파일을 만듭니다.
{ "mcpServers": { "whatsapp": { "command": "node", "args": [ "PATH_TO/dist/index.js" ] } } }
PATH_TO 저장소의 절대 경로로 바꾸세요.
Claude Desktop 구성 디렉토리에 claude_desktop_config.json 이라는 이름으로 저장하세요.
- macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
- Windows: %APPDATA%\Claude\claude_desktop_config.json
- 리눅스: ~/.config/Claude/claude_desktop_config.json
Claude Desktop을 다시 시작하세요

커서에 연결

커서에 대한 구성 파일을 만듭니다.
{ "mcpServers": { "whatsapp": { "command": "node", "args": [ "PATH_TO/dist/index.js" ] } } }
PATH_TO 저장소의 절대 경로로 바꾸세요.
커서 구성 디렉토리에 mcp.json 으로 저장하세요.
- macOS/Linux: ~/.cursor/mcp.json
- 윈도우: %USERPROFILE%\.cursor\mcp.json
커서 재시작

입증

서버를 처음 실행할 때 WhatsApp으로 인증해야 합니다.

MCP 서버를 시작합니다
중요: QR 코드를 생성하려면 get_qr_code 도구를 사용해야 합니다.
- Claude 또는 다른 AI 도우미에서 "WhatsApp 인증을 위해 get_qr_code 도구를 사용하세요"라고 명시적으로 요청합니다.
- 도우미는 이 도구를 호출하고 QR 코드 이미지를 표시합니다.
WhatsApp 모바일 앱으로 QR 코드를 스캔하세요
- 휴대폰에서 WhatsApp을 엽니다
- 설정 > 연결된 기기 > 기기 연결로 이동하세요.
- 표시된 QR 코드에 휴대폰 카메라를 대세요

세션은 whatsapp-sessions 디렉터리에 로컬로 저장되며 이후 실행 시 자동으로 재사용됩니다. QR 코드를 사용하여 인증하지 않으면 WhatsApp 기능을 사용할 수 없습니다.

인증 상태 및 로그아웃

현재 인증 상태를 확인하고 세션을 관리할 수 있습니다.

check_auth_status 도구를 사용하여 현재 인증되었는지 확인하세요.
다른 WhatsApp 계정으로 인증하거나 다시 인증해야 하는 경우:
1. logout 도구를 사용하여 현재 세션에서 로그아웃하세요.
2. 그런 다음 get_qr_code 도구를 사용하여 새 QR 코드로 인증하세요.

이 기능은 다음과 같은 경우에 특히 유용합니다.

다양한 WhatsApp 계정 간에 전환하고 싶습니다.
세션이 만료되었거나 무효화되었습니다.
연결 문제가 발생하여 다시 인증해야 합니다.

사용 가능한 MCP 도구

입증

get_qr_code - WhatsApp 웹 인증을 위한 QR 코드를 받으세요
check_auth_status - 현재 WhatsApp에서 인증되었는지 확인하세요
logout - WhatsApp에서 로그아웃하고 현재 세션을 지웁니다.

콘택트 렌즈

search_contacts - 이름이나 전화번호로 연락처 검색
get_contact - 특정 연락처에 대한 정보 가져오기

채팅

list_chats - 메타데이터를 사용하여 사용 가능한 채팅 나열
get_chat - 특정 채팅에 대한 정보를 가져옵니다
get_direct_chat_by_contact - 특정 연락처와 직접 채팅 찾기

메시지

list_messages - 선택적 필터를 사용하여 메시지 검색
get_message - ID로 특정 메시지를 가져옵니다.
send_message - 채팅방에 문자 메시지 보내기

메디아

send_file - 파일(이미지, 비디오, 문서)을 채팅으로 전송합니다.
send_audio_message - 오디오 메시지(음성 메모)를 보냅니다.
download_media - 메시지에서 미디어 다운로드

브라우저 프로세스 관리

이 MCP 서버는 Puppeteer를 사용하여 WhatsApp 웹 연결을 위한 Chrome 브라우저를 제어합니다. 이 서버에는 고아 Chrome 프로세스를 방지하는 강력한 브라우저 프로세스 관리 시스템이 포함되어 있습니다.

자동 브라우저 정리

서버는 자동으로 다음을 수행합니다.

PID 추적 시스템을 사용하여 Chrome 브라우저 프로세스를 추적합니다.
시작 시 고아 프로세스를 정리합니다.
종료 시 브라우저 프로세스를 제대로 닫습니다.
.chrome-pids.json 에 브라우저 PID 기록을 유지합니다.

수동 브라우저 정리

자동으로 정리되지 않은 버려진 Chrome 프로세스가 발견되면 포함된 정리 유틸리티를 사용할 수 있습니다.

npm run cleanup-browsers

이 유틸리티는 다음을 수행합니다.

WhatsApp 웹과 관련이 있을 수 있는 Chrome 프로세스를 검색합니다.
잠재적으로 고아가 된 프로세스 목록 표시
해지하기 전에 확인을 요청하세요
PID 추적 파일 정리

개발

프로젝트 구조

src/index.ts - 진입점
src/server.ts - MCP 서버 구현
src/services/whatsapp.ts - WhatsApp 웹 서비스
src/tools/ - 다양한 WhatsApp 기능에 대한 도구 구현
src/types/ - TypeScript 유형 정의
src/utils/ - 유틸리티 함수

스크립트

npm run build - TypeScript 코드 빌드
npm run dev - watch를 사용하여 개발 모드로 실행
npm run lint - ESLint 실행
npm run format - Prettier로 코드 포맷하기
npm run cleanup-browsers - 고아가 된 Chrome 브라우저 프로세스를 감지하고 정리합니다.

문제 해결

인증 문제

QR 코드가 나타나지 않으면 서버를 다시 시작해 보세요.
이미 인증된 경우 QR 코드가 표시되지 않습니다( check_auth_status 사용하여 확인하세요)
재인증이 필요한 경우 먼저 logout 도구를 사용한 다음 새 QR 코드를 요청하세요.
WhatsApp은 연결된 기기 수를 제한합니다. 기존 기기를 제거해야 할 수도 있습니다.
"현재 사용 가능한 QR 코드가 없습니다"라는 메시지가 표시되지만 이미 인증된 경우 이는 정상적인 동작입니다. check_auth_status 사용하여 인증 상태를 확인하세요.

연결 문제

인터넷 연결이 안정적인지 확인하세요
연결이 실패하면 서버를 다시 시작해 보세요.
자세한 오류 메시지는 로그에서 확인하세요.

브라우저 프로세스 문제

CPU 사용량이나 메모리 소모가 높은 경우 Chrome 프로세스가 고아일 수 있습니다.
npm run cleanup-browsers 실행하여 고아 프로세스를 감지하고 정리합니다.
서버가 자주 충돌하는 경우 고아 프로세스를 확인하고 정리하세요.
Windows에서는 명령줄에 "headless"를 사용하여 작업 관리자를 사용하여 여러 Chrome 프로세스를 찾을 수도 있습니다.
Linux/macOS에서는 ps aux | grep chrome 사용하여 고아 프로세스를 확인하세요.

특허

MIT

이 프로젝트는 lharries 가 만든 원래 whatsapp-mcp 의 TypeScript 포트입니다.

Integrations