wazap-mcp

██╗    ██╗ █████╗ ███████╗ █████╗ ██████╗
██║    ██║██╔══██╗╚══███╔╝██╔══██╗██╔══██╗
██║ █╗ ██║███████║  ███╔╝ ███████║██████╔╝
██║███╗██║██╔══██║ ███╔╝  ██╔══██║██╔═══╝
╚███╔███╔╝██║  ██║███████╗██║  ██║██║
 ╚══╝╚══╝ ╚═╝  ╚═╝╚══════╝╚═╝  ╚═╝╚═╝

당신의 AI 에이전트를 위한 WhatsApp. WhatsApp 계정(채팅, 메시지, 미디어, 연락처, 그룹)을 모든 MCP 클라이언트가 호출할 수 있는 22개의 도구 뒤에 두는 MCP 서버입니다. 페어링 코드 로그인, 브라우저 불필요, 전화번호 리셀러 불필요, 약 20MB의 RAM만 사용합니다.

Baileys 기반으로, WebSocket을 통해 WhatsApp 멀티디바이스 프로토콜을 사용합니다.

시작하기

npm 패키지는 wazap-mcp이고, 설치되는 명령어는 wazap입니다.

npx wazap-mcp setup

이것이 설치의 전부입니다. 계정을 연결하고, 이 머신에 설치된 MCP 클라이언트를 찾아서, 그들의 설정을 작성하고 무엇을 재시작해야 하는지 알려줍니다.

또는 에이전트가 하게 하세요. 이걸 붙여넣으세요:

WhatsApp을 설정해 줘: npx wazap-mcp setup --agent를 실행하고 출력되는 내용을 따라 해.

그런 다음 에이전트에게 물어보세요: "오늘 WhatsApp에서 내가 놓친 게 뭐야?"

아래는 setup이 대신 실행하는 단계들입니다. 각 단계는 직접 실행하고 싶을 때 여전히 개별 명령어로 사용할 수 있습니다.

npx wazap-mcp login은 QR 코드를 표시합니다. 설정 → 연결된 기기 → 기기 연결에서 스캔하세요. 카메라가 없거나 SSH로 연결 중인가요? npx wazap-mcp login --phone +15550100은 전화번호로 연결 아래에 입력할 8자리 코드를 출력합니다. 마지막에 에이전트가 메시지를 보내도 되는지 묻습니다. 직접 허락하지 않는 한 기본값은 아니요이며, npx wazap-mcp config writes on으로 나중에 변경할 수 있습니다.

npx wazap-mcp connect claude-code는 한 클라이언트에 대한 MCP 항목을 작성합니다. 클라이언트 연결 아래 표에 나머지가 있습니다.

npx wazap-mcp를 단독으로 실행하는 것은 안전합니다. 현재 상태와 다음에 할 일을 출력할 뿐 서버를 시작하지 않습니다. 문제가 있을 때 npx wazap-mcp status가 가장 먼저 실행할 것입니다. Node, 데이터 디렉터리, 잠금, 자격 증명, 최신 버전 여부를 확인하고 문제가 있는 항목 옆에 해결 방법을 출력합니다.

클라이언트 연결

wazap connect <client>는 파일의 다른 내용을 유지하면서 항목을 작성하고, 첫 변경 전에 한 번 백업합니다. --dry-run은 작성할 내용을 미리 보여줍니다.

모든 MCP 클라이언트는 동일하게 작동합니다. 명령어는 npx -y wazap-mcp, 전송 방식은 stdio입니다. 에이전트에게 먼저 learn을 호출하라고 하세요. ID 형식, 워크플로, 모든 오류 코드와 그에 대한 조치를 반환합니다.

{
  "mcpServers": {
    "whatsapp": {
      "command": "npx",
      "args": ["-y", "wazap-mcp"]
    }
  }
}

Claude Desktop, Cursor, Gemini CLI는 정확히 그 형식을 사용합니다. VS Code는 servers 아래에 중첩하고 command 옆에 "type": "stdio"를 요구합니다. Codex CLI는 TOML입니다:

[mcp_servers.whatsapp]
command = "npx"
args = ["-y", "wazap-mcp"]

skills/ 폴더는 Agent Skills 형식을 따르므로 Codex, Cursor 및 기타 스킬 인식 에이전트가 동일한 5개 스킬을 로드할 수 있습니다.

Related MCP server: wa-bridge

도구

모든 메시지는 비어 있지 않은 text와 함께 반환됩니다. 미디어 및 시스템 메시지는 [image] caption, [voice message], [deleted], [poll] Pizza or pasta? 같은 자리 표시자를 포함합니다. 타임스탬프는 머신의 UTC 오프셋이 포함된 ISO 8601 형식이며, 2h ago 같은 사람이 읽기 쉬운 age도 함께 제공됩니다.

스킬

wazap은 도구 자체가 아니라 도구 뒤의 워크플로를 에이전트에게 가르치는 5개의 Agent Skills를 제공합니다:

모든 것(서버와 스킬)을 Claude Code 플러그인으로 설치:

/plugin marketplace add razvangirgiz/wazap
/plugin install wazap@wazap

또는 skills/<name>/을 에이전트가 읽는 아무 스킬 디렉터리에 복사하세요.

오류

모든 실패는 스택 트레이스 대신 구조화된 { error, message, fix }로 반환되므로 에이전트가 재시도할지, 사용자에게 물어볼지, 중단할지 결정할 수 있습니다.

데이터 디렉터리

모든 것은 ~/.wazap에 저장됩니다(--data-dir 또는 WAZAP_DATA_DIR로 재정의 가능). 디렉터리는 0700, 자격 증명 파일은 0600 권한으로 생성됩니다:

~/.wazap/
  auth/         WhatsApp credentials — treat this like a password
  media/        downloads from download_media
  history/      per-chat message history, so a restart is not amnesia
  store.json    chat-list snapshot
  server.lock   pid of the running server
  daemon.json   loopback endpoint a second wazap bridges to
  .env          optional settings, see .env.example

자격 증명 쓰기는 임시 파일에 기록한 후 이름을 바꿔 제자리에 넣으므로, 쓰기 도중 프로세스가 종료되어도 휴대폰을 다시 연결할 필요가 없습니다.

여러 클라이언트 동시 사용

Claude Desktop, Claude Code, Cursor는 각자 자체 wazap을 실행합니다. WhatsApp은 연결된 기기당 소켓 하나만 허용하므로, 이들은 세션을 두고 다투는 대신 하나의 세션을 공유합니다. 데이터 디렉터리에서 첫 번째 wazap이 세션을 소유하고 127.0.0.1에 MCP 엔드포인트를 엽니다. 이후 실행되는 모든 wazap은 그 엔드포인트를 통해 브리지로 연결됩니다. 설정할 것이 없으며, 어떤 클라이언트도 차이를 알아챌 수 없습니다. 소유자는 <data-dir>/daemon.json(0600)에 자신의 pid, 포트, 그리고 브리지가 인증에 사용하는 토큰을 게시합니다.

브리지는 소유자가 노출하는 것을 그대로 제공하므로, --read-only로 시작된 소유자는 클라이언트가 어떤 플래그로 실행되었든 모든 클라이언트를 읽기 전용으로 만듭니다.

소유자가 종료되면 브리지도 함께 종료되고, 클라이언트가 다음에 시작하는 wazap이 새 소유자가 됩니다.

WAZAP_NO_SHARE=1은 옵트아웃합니다. 같은 디렉터리에서 두 번째 wazap이 실행되면 이미 실행 중인 pid를 명시하며 코드 2로 종료됩니다. 명시적인 --http는 브리지가 아니라 독자적인 서버이며, 같은 방식으로 거부됩니다.

읽기 전용 모드

쓰기는 옵트인 방식입니다. login은 한 번 물어보고 답을 <data-dir>/.env에 저장합니다. wazap config writes on|off로 변경할 수 있고, wazap config만 실행하면 모든 유효 설정과 그 출처를 출력합니다.

WAZAP_READ_ONLY=1 또는 wazap serve --read-only는 쓰기 도구를 아예 등록하지 않습니다. 에이전트는 그 도구들을 볼 수 없으므로, 실수로라도 내 번호로 누군가에게 메시지를 보낼 수 없습니다. 연결된 계정이 개인 계정일 때 유용합니다.

쓰기는 또한 WAZAP_RATE_LIMIT(기본 20, 0은 비활성화)으로 분당 호출 횟수가 제한됩니다. 사람보다 빠르게 보내는 것은 계정이 차단되는 원인입니다.

HTTP 모드

WAZAP_READ_TOKEN=$(openssl rand -hex 32) \
WAZAP_WRITE_TOKEN=$(openssl rand -hex 32) \
npx wazap-mcp serve --http --host 0.0.0.0 --port 8766

/mcp에서 Streamable HTTP를 제공하며, /healthz에 상태 확인 엔드포인트가 있습니다. 두 개의 베어러 토큰이 있습니다. 읽기 토큰은 읽기 도구를 얻고, 쓰기 토큰은 쓰기 도구도 잠금 해제합니다. 따라서 읽기 토큰이 유출되어도 누구에게도 메시지를 보낼 수 없습니다. wazap은 읽기 토큰 없이는 루프백이 아닌 주소에 바인딩하는 것을 거부합니다.

자체 호스팅

에이전트가 노트북에 없을 때 — 다른 머신, VPS, 클라이언트의 인프라 — wazap을 자체 서버에서 실행하세요. 세션은 그 서버에 유지되며, 어떤 제3자도 거치지 않습니다.

systemd 사용 시

npm install -g wazap-mcp
sudo useradd --system --home /var/lib/wazap --create-home wazap
sudo -u wazap WAZAP_DATA_DIR=/var/lib/wazap wazap login --phone +15550100   # pairing code works over SSH
sudo -u wazap tee /var/lib/wazap/.env >/dev/null <<END
WAZAP_READ_TOKEN=$(openssl rand -hex 32)
WAZAP_WRITE_TOKEN=$(openssl rand -hex 32)
END
sudo curl -fsSL https://raw.githubusercontent.com/razvangirgiz/wazap/main/deploy/wazap.service -o /etc/systemd/system/wazap.service
sudo systemctl enable --now wazap
curl -s http://127.0.0.1:8766/healthz

유닛은 루프백에만 바인딩합니다. 두 줄짜리 deploy/Caddyfile(호스트 이름을 편집한 후 caddy run --config deploy/Caddyfile)로 TLS를 앞에 두거나, 아무 리버스 프록시를 사용한 다음 클라이언트를 Authorization: Bearer <읽기 또는 쓰기 토큰>과 함께 https://your-host/mcp로 연결하세요.

Docker 사용 시

git clone https://github.com/razvangirgiz/wazap && cd wazap
printf 'WAZAP_READ_TOKEN=%s\nWAZAP_WRITE_TOKEN=%s\n' $(openssl rand -hex 32) $(openssl rand -hex 32) > .env
docker compose run --rm wazap login --phone +15550100   # once; the session lands in the wazap-data volume
docker compose up -d
curl -s http://127.0.0.1:8766/healthz

컨테이너는 8766을 루프백에만 게시합니다. 앞에 동일한 TLS 프록시를 추가하세요. 업그레이드는 git pull && docker compose up -d --build이며, 볼륨이 세션을 유지합니다.

어떤 클라이언트가 접근할 수 있나요

Claude Code, Claude Desktop, Cursor, Codex, VS Code 및 "MCP URL + 헤더" 필드가 있는 모든 클라이언트는 베어러 토큰으로 연결할 수 있습니다. claude.ai Connectors는 정적 토큰 대신 OAuth를 요구하므로 아직 자체 호스팅 wazap을 사용할 수 없습니다. 읽기만 필요한 클라이언트에는 읽기 토큰을 유지하고, 쓰기 토큰은 신중하게 배포하세요.

설정

플래그가 환경 변수를 이기고, 환경 변수가 <data-dir>/.env를 이깁니다.

알려진 제한 사항

• 비공식. Baileys는 WhatsApp 다중 기기 프로토콜을 리버스 엔지니어링합니다. 이것은 WhatsApp Business API가 아니며 Meta가 지원하지 않습니다.

• 차단 위험은 실재합니다. 자동 전송, 대량 메시징 또는 사람이 그럴듯하게 입력하지 않을 어떤 행위든 번호가 차단될 수 있으며, 여기서는 복구할 수 없습니다. 속도 제한이 도움이 되지만 보장은 아닙니다.

• 미디어 키는 만료됩니다. WhatsApp은 서버에서 오래된 첨부 파일을 삭제하므로, 오래된 메시지에 대한 download_media는 MEDIA_UNAVAILABLE을 반환합니다.

• 기록은 휴대폰이 동기화하는 범위입니다. wazap은 WhatsApp이 연결된 기기에 제공하는 기록을 볼 뿐, 휴대폰의 전체 아카이브는 아닙니다. before가 있는 read_messages는 WhatsApp이 여전히 보관하는 범위 내에서 더 많은 기록을 요청합니다.

• @lid ID. 최신 계정은 전화번호 대신 개인정보 ID로 주소가 지정됩니다. wazap은 매핑을 학습한 경우 이를 전화번호로 다시 변환하고, 학습하지 못한 경우 @lid를 그대로 전달합니다.

• 휴대폰이 계속 연결 가능해야 합니다. 휴대폰이 충분히 오래 오프라인이면 연결된 기기는 수신을 중단합니다. get_status가 hint에 이를 알려줍니다.

개발

npm install
npm run typecheck
npm test                       # builds, then runs node --test
node test/smoke-stdio.mjs      # drives the built binary over MCP stdio
npm run dev -- status          # run from source with tsx

npm test는 WhatsApp 세션이 필요 없습니다. stdio 스모크 테스트는 빌드된 바이너리를 임시 데이터 디렉터리로 실행하고, 연결되지 않은 설치에서도 initialize, tools/list, get_status에 응답하는지 확인합니다.

MIT 라이선스입니다.