왓츠앱 웹 MCP

PR 체크

모델 컨텍스트 프로토콜(MCP)을 통해 WhatsApp 웹과 AI 모델을 연결하는 Node.js 애플리케이션입니다. 이 프로젝트는 WhatsApp과의 프로그래밍 방식 상호작용을 위한 표준화된 인터페이스를 제공하여 AI 기반 워크플로를 통해 자동 메시징, 연락처 관리 및 그룹 채팅 기능을 지원합니다.

개요

WhatsApp Web MCP는 다음을 통해 WhatsApp Web과 AI 모델 간의 원활한 통합을 제공합니다.

MCP(Model Context Protocol)를 통한 표준화된 인터페이스 생성
WhatsApp 기능에 대한 MCP 서버 액세스 제공
SSE 또는 명령 모드를 통해 유연한 배포 옵션 제공
직접 WhatsApp 클라이언트 통합과 API 기반 연결을 모두 지원합니다.

Related MCP server: MCP Evolution API

부인 성명

중요 : 이 도구는 테스트 목적으로만 사용되며 실제 운영 환경에서는 사용하면 안 됩니다.

WhatsApp 웹 프로젝트의 면책 조항:

이 프로젝트는 WhatsApp 또는 그 자회사나 계열사와 제휴, 제휴, 승인, 보증 또는 어떤 방식으로든 공식적으로 연결되어 있지 않습니다. 공식 WhatsApp 웹사이트는 whatsapp.com에서 확인하실 수 있습니다. "WhatsApp" 및 관련 이름, 상표, 엠블럼, 이미지는 해당 소유자의 등록 상표입니다. 또한, 이 방법을 사용하더라도 차단되지 않을 것이라는 보장은 없습니다. WhatsApp은 플랫폼에서 봇이나 비공식 클라이언트를 허용하지 않으므로 완전히 안전하다고 할 수는 없습니다.

학습 자료

실제 상황에서 WhatsApp Web MCP를 사용하는 방법에 대해 자세히 알아보려면 다음 문서를 확인하세요.

설치

저장소를 복제합니다.
지엑스피1
전역적으로 설치하거나 npx와 함께 사용:
# Install globally npm install -g . # Or use with npx directly npx .
Docker로 빌드:
docker build . -t wweb-mcp:latest

구성

명령줄 옵션

옵션	별명	설명	선택	기본
`--mode`	`-m`	실행 모드	`mcp` , `whatsapp-api`	`mcp`
`--mcp-mode`	`-c`	MCP 연결 모드	`standalone` , `api`	`standalone`
`--transport`	`-t`	MCP 전송 모드	`sse` , `command`	`sse`
`--sse-port`	`-p`	SSE 서버용 포트	-	`3002`
`--api-port`	-	WhatsApp API 서버용 포트	-	`3001`
`--auth-data-path`	`-a`	인증 데이터를 저장하는 경로	-	`.wwebjs_auth`
`--auth-strategy`	`-s`	인증 전략	`local` , `none`	`local`
`--api-base-url`	`-b`	API 모드를 사용할 때 MCP에 대한 API 기반 URL	-	`http://localhost:3001/api`
`--api-key`	`-k`	API 모드를 사용할 때 WhatsApp Web REST API에 대한 API 키	-	`''`

API 키 인증

API 모드에서 실행할 경우 WhatsApp API 서버는 API 키를 사용한 인증을 요구합니다. API 키는 WhatsApp API 서버를 시작할 때 자동으로 생성되며 로그에 표시됩니다.

WhatsApp API key: 1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef

MCP 서버를 WhatsApp API 서버에 연결하려면 --api-key 또는 -k 옵션을 사용하여 이 API 키를 제공해야 합니다.

npx wweb-mcp --mode mcp --mcp-mode api --api-base-url http://localhost:3001/api --api-key 1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef

API 키는 인증 데이터 디렉토리( --auth-data-path 로 지정)에 저장되며 WhatsApp API 서버를 다시 시작할 때까지 유지됩니다.

인증 방법

로컬 인증(권장)

QR 코드를 한 번 스캔하세요
세션 간에 자격 증명이 유지됩니다.
장기 작동 시 더욱 안정적임

인증 없음

기본 방법
시작할 때마다 QR 코드 스캔이 필요합니다.
테스트 및 개발에 적합

웹훅 구성

인증 데이터 디렉터리( --auth-data-path 로 지정)에 webhook.json 파일을 만들어서 들어오는 WhatsApp 메시지를 수신하도록 웹훅을 구성할 수 있습니다.

웹훅 JSON 형식

{ "url": "https://your-webhook-endpoint.com/incoming", "authToken": "your-optional-authentication-token", "filters": { "allowedNumbers": ["+1234567890", "+0987654321"], "allowPrivate": true, "allowGroups": false } }

구성 옵션

옵션	유형	설명
`url`	끈	메시지 데이터가 전송될 웹훅 엔드포인트 URL
`authToken`	문자열(선택 사항)	인증 토큰은 Authorization 헤더에 Bearer 토큰으로 포함됩니다.
`filters.allowedNumbers`	배열(선택 사항)	메시지를 수신할 전화번호 목록입니다. 이 값을 입력하면 해당 번호에서 수신된 메시지만 웹훅을 트리거합니다.
`filters.allowPrivate`	부울(선택 사항)	웹훅에 개인 메시지를 보낼지 여부입니다. 기본값: `true`
`filters.allowGroups`	부울(선택 사항)	웹훅에 그룹 메시지를 보낼지 여부입니다. 기본값: `true`

웹훅 페이로드

메시지가 수신되어 필터를 통과하면 다음 JSON 페이로드와 함께 구성된 URL로 POST 요청이 전송됩니다.

{ "from": "+1234567890", "name": "Contact Name", "message": "Hello, world!", "isGroup": false, "timestamp": 1621234567890, "messageId": "ABCDEF1234567890" }

용법

실행 모드

WhatsApp API 서버

REST 엔드포인트를 통해 WhatsApp 기능을 노출하는 독립형 WhatsApp API 서버를 실행합니다.

npx wweb-mcp --mode whatsapp-api --api-port 3001

MCP 서버(독립형)

WhatsApp Web에 직접 연결되는 MCP 서버를 실행합니다.

npx wweb-mcp --mode mcp --mcp-mode standalone --transport sse --sse-port 3002

MCP 서버(API 클라이언트)

WhatsApp API 서버에 연결하는 MCP 서버를 실행합니다.

# First, start the WhatsApp API server and note the API key from the logs npx wweb-mcp --mode whatsapp-api --api-port 3001 # Then, start the MCP server with the API key npx wweb-mcp --mode mcp --mcp-mode api --api-base-url http://localhost:3001/api --api-key YOUR_API_KEY --transport sse --sse-port 3002

사용 가능한 도구

도구	설명	매개변수
`get_status`	WhatsApp 클라이언트 연결 상태 확인	없음
`send_message`	WhatsApp 연락처로 메시지 보내기	`number` : `message` 를 보낼 전화번호 : 보낼 텍스트 내용
`search_contacts`	이름이나 번호로 연락처 검색	`query` : 연락처를 찾기 위한 검색어
`get_messages`	특정 채팅에서 메시지 검색	`number` : 메시지를 받을 전화번호 `limit` (선택사항): 검색할 메시지 수
`get_chats`	모든 WhatsApp 채팅 목록 받기	없음
`create_group`	새로운 WhatsApp 그룹을 만드세요	`name` : 그룹 `participants` 이름 : 추가할 전화번호 배열
`add_participants_to_group`	기존 그룹에 참가자 추가	`groupId` : 그룹 `participants` 의 ID : 추가할 전화번호 배열
`get_group_messages`	그룹에서 메시지 검색	`groupId` : 그룹 `limit` 의 ID(선택 사항): 검색할 메시지 수
`send_group_message`	그룹에 메시지 보내기	`groupId` : 그룹 `message` 의 ID : 보낼 텍스트 콘텐츠
`search_groups`	이름, 설명 또는 회원 이름으로 그룹 검색	`query` : 그룹을 찾기 위한 검색어
`get_group_by_id`	특정 그룹에 대한 자세한 정보를 얻으세요	`groupId` : 가져올 그룹의 ID
`download_media_from_message`	메시지에서 미디어 다운로드	`messageId` : 다운로드할 미디어가 포함된 메시지의 ID
`send_media_message`	WhatsApp 연락처에 미디어 메시지 보내기	`number` : 보낼 전화번호 `source` : URI 체계가 있는 미디어 소스(URL의 경우 `http://` 또는 `https://` , 로컬 파일의 경우 `file://` ) `caption` (선택 사항): 미디어에 대한 텍스트 캡션

사용 가능한 리소스

리소스 URI	설명
`whatsapp://contacts`	모든 WhatsApp 연락처 목록
`whatsapp://messages/{number}`	특정 채팅의 메시지
`whatsapp://chats`	모든 WhatsApp 채팅 목록
`whatsapp://groups`	모든 WhatsApp 그룹 목록
`whatsapp://groups/search`	이름, 설명 또는 회원 이름으로 그룹 검색
`whatsapp://groups/{groupId}/messages`	특정 그룹의 메시지

REST API 엔드포인트

연락처 및 메시지

엔드포인트	방법	설명	매개변수
`/api/status`	얻다	WhatsApp 연결 상태 가져오기	없음
`/api/contacts`	얻다	모든 연락처 가져오기	없음
`/api/contacts/search`	얻다	연락처 검색	`query` : 검색어
`/api/chats`	얻다	모든 채팅 받기	없음
`/api/messages/{number}`	얻다	채팅에서 메시지 받기	`limit` (쿼리): 메시지 수
`/api/send`	우편	메시지 보내기	`number` : 수신자 `message` : 메시지 내용
`/api/send/media`	우편	미디어 메시지 보내기	`number` : 수신자 `source` : URI 체계가 있는 미디어 소스(URL의 경우 `http://` 또는 `https://` , 로컬 파일의 경우 `file://` ) `caption` (선택 사항): 텍스트 캡션
`/api/messages/{messageId}/media/download`	우편	메시지에서 미디어 다운로드	없음

그룹 관리

엔드포인트	방법	설명	매개변수
`/api/groups`	얻다	모든 그룹 가져오기	없음
`/api/groups/search`	얻다	그룹 검색	`query` : 검색어
`/api/groups/create`	우편	새 그룹을 만듭니다	`name` : 그룹 이름 `participants` : 숫자 배열
`/api/groups/{groupId}`	얻다	특정 그룹에 대한 자세한 정보를 얻으세요	없음
`/api/groups/{groupId}/messages`	얻다	그룹으로부터 메시지 받기	`limit` (쿼리): 메시지 수
`/api/groups/{groupId}/participants/add`	우편	그룹에 멤버 추가	`participants` : 숫자 배열
`/api/groups/send`	우편	그룹에 메시지 보내기	`groupId` : 그룹 ID `message` : 메시지 내용

AI 통합

Claude 데스크톱 통합

옵션 1: NPX 사용

WhatsApp API 서버 시작:
npx wweb-mcp -m whatsapp-api -s local
WhatsApp 모바일 앱으로 QR 코드를 스캔하세요
로그에 표시된 API 키를 확인하세요.
WhatsApp API key: 1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef
Claude Desktop 구성에 다음을 추가하세요.
{ "mcpServers": { "whatsapp": { "command": "npx", "args": [ "wweb-mcp", "-m", "mcp", "-s", "local", "-c", "api", "-t", "command", "--api-base-url", "http://localhost:3001/api", "--api-key", "1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef" ] } } }

옵션 2: Docker 사용

Docker에서 WhatsApp API 서버 시작:
docker run -i -p 3001:3001 -v wweb-mcp:/wwebjs_auth --rm wweb-mcp:latest -m whatsapp-api -s local -a /wwebjs_auth
WhatsApp 모바일 앱으로 QR 코드를 스캔하세요
로그에 표시된 API 키를 확인하세요.
WhatsApp API key: 1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef
Claude Desktop 구성에 다음을 추가하세요.
{ "mcpServers": { "whatsapp": { "command": "docker", "args": [ "run", "-i", "--rm", "wweb-mcp:latest", "-m", "mcp", "-s", "local", "-c", "api", "-t", "command", "--api-base-url", "http://host.docker.internal:3001/api", "--api-key", "1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef" ] } } }
Claude Desktop을 다시 시작하세요
WhatsApp 기능은 Claude의 인터페이스를 통해 사용할 수 있습니다.

건축학

이 프로젝트는 관심사를 명확하게 분리하여 구성됩니다.

구성 요소

WhatsAppService : WhatsApp과 상호 작용하기 위한 핵심 비즈니스 로직
WhatsAppApiClient : WhatsApp API에 연결하기 위한 클라이언트
API 라우터 : REST API를 위한 Express 경로
MCP 서버 : 모델 컨텍스트 프로토콜 구현

배포 옵션

WhatsApp API 서버 : 독립형 REST API 서버
MCP 서버(독립형) : WhatsApp 웹에 직접 연결
MCP 서버(API 클라이언트) : WhatsApp API 서버에 연결

이 아키텍처는 다음을 포함한 유연한 배포 시나리오를 허용합니다.

다른 컴퓨터에서 API 서버와 MCP 서버 실행
기존 API 서버에 대한 클라이언트로 MCP 서버 사용
단순성을 위해 모든 것을 단일 머신에서 실행

개발

프로젝트 구조

src/ ├── whatsapp-client.ts # WhatsApp Web client implementation ├── whatsapp-service.ts # Core business logic ├── whatsapp-api-client.ts # Client for the WhatsApp API ├── api.ts # REST API router ├── mcp-server.ts # MCP protocol implementation └── main.ts # Application entry point

소스에서 빌드

npm run build

테스트

이 프로젝트에서는 단위 테스트를 위해 Jest를 사용합니다. 테스트를 실행하려면 다음을 수행하세요.

# Run all tests npm test # Run tests in watch mode during development npm run test:watch # Generate test coverage report npm run test:coverage

린팅 및 포맷팅

이 프로젝트에서는 코드 품질과 형식을 위해 ESLint와 Prettier를 사용합니다.

# Run linter npm run lint # Fix linting issues automatically npm run lint:fix # Format code with Prettier npm run format # Validate code (lint + test) npm run validate

린팅 구성은 TypeScript 모범 사례를 적용하고 프로젝트 전체에서 일관된 코드 스타일을 유지합니다.

출판

이 프로젝트는 npm에 자동으로 게시하기 위해 GitHub Actions를 사용합니다. 워크플로는 다음을 처리합니다.

버전 증가( patch , minor 또는 major )
버전 앞에 'v' 접두사를 붙인 Git 태그(예: v0.2.1)
GitHub 비밀을 사용하여 npm에 게시

새 버전을 출시하려면:

GitHub 저장소 작업 탭으로 이동
"패키지 게시" 워크플로를 선택하세요
"워크플로 실행"을 클릭하세요
버전 증가 유형(패치, 마이너 또는 메이저)을 선택하세요
게시 프로세스를 시작하려면 "워크플로 실행"을 클릭하세요.

이 워크플로를 사용하려면 GitHub 저장소에 NPM_TOKEN 비밀번호를 구성해야 합니다.

문제 해결

Claude Desktop 통합 문제

Claude에서 wweb-mcp를 명령 독립 실행형 모드로 시작할 수 없습니다. Claude가 두 개 이상의 프로세스를 여러 번 열고, 각 wweb-mcp가 동일한 WhatsApp 인증을 공유할 수 없는 퍼펫티어 세션을 열어야 하기 때문입니다. 이러한 제한으로 인해 Claude와의 원활한 통합을 위해 앱을 MCP 모드와 API 모드로 분리했습니다.

특징

메시지 보내기 및 받기
미디어 메시지 보내기(이미지만)
메시지에서 미디어 다운로드(이미지, 오디오, 문서)
그룹 채팅 관리
연락처 관리 및 검색
메시지 기록 검색

곧 출시될 기능

모든 미디어 파일 유형(비디오, 오디오, 문서) 전송 지원
일반적인 시나리오에 대한 향상된 메시지 템플릿
고급 그룹 관리 기능
연락처 관리(연락처 추가/삭제)
향상된 오류 처리 및 복구

기여하다

저장소를 포크하세요
기능 브랜치 생성
변경 사항을 커밋하세요
지점으로 푸시하세요
풀 리퀘스트 만들기

귀하의 PR을 확인하십시오:

기존 코드 스타일을 따릅니다
적절한 테스트가 포함되어 있습니다
필요에 따라 문서를 업데이트합니다.
변경 사항을 자세히 설명합니다.

종속성

왓츠앱 웹.js

이 프로젝트는 WhatsApp 웹 브라우저 앱을 통해 연결되는 WhatsApp 웹용 비공식 JavaScript 클라이언트 라이브러리인 whatsapp-web.js를 사용합니다. 자세한 내용은 whatsapp-web.js GitHub 저장소를 참조하세요.

특허

이 프로젝트는 MIT 라이선스에 따라 라이선스가 부여되었습니다. 자세한 내용은 라이선스 파일을 참조하세요.

벌채 반출

WhatsApp Web MCP에는 Winston으로 구축된 강력한 로깅 시스템이 포함되어 있습니다. 로깅 시스템은 다음과 같은 기능을 제공합니다.

다양한 로그 수준(오류, 경고, 정보, http, 디버그)
색상이 지정된 로그가 포함된 콘솔 출력
API 엔드포인트에 대한 HTTP 요청/응답 로깅
구조화된 오류 처리
환경 인식 로그 수준(개발 대 생산)
MCP 명령 모드에서 실행할 때 모든 로그가 stderr로 전송됩니다.

로그 수준

이 애플리케이션은 자세한 정도에 따라 다음과 같은 로그 수준을 지원합니다.

오류 - 응용 프로그램이 작동하지 못하게 하는 심각한 오류
경고 - 애플리케이션을 중지시키지는 않지만 주의가 필요한 경고
info - 애플리케이션 상태 및 이벤트에 대한 일반 정보
http - HTTP 요청/응답 로깅
디버그 - 자세한 디버깅 정보

로그 수준 구성

--log-level 또는 -l 플래그를 사용하여 애플리케이션을 시작할 때 로그 수준을 구성할 수 있습니다.

npm start -- --log-level=debug

또는 글로벌 설치를 사용하는 경우:

wweb-mcp --log-level=debug

명령 모드 로깅

MCP 명령 모드( --mode mcp --transport command )에서 실행할 경우 모든 로그는 stderr로 전송됩니다. 이는 stdout을 데이터 출력에 사용하고 stderr을 로깅 및 진단에 사용하는 명령줄 도구에 중요합니다. 이를 통해 stdout을 통한 MCP 프로토콜 통신이 로그 메시지에 의해 방해받지 않도록 할 수 있습니다.

테스트 환경

테스트 환경( NODE_ENV=test 또는 Jest로 실행하는 경우)에서 로거는 테스트 환경에 적합하도록 자동으로 동작을 조정합니다.