📱 WhatsApp MCP — 원격 HTTP/SSE 서버

WhatsApp용 모델 컨텍스트 프로토콜(MCP) 서버, whatsapp-web.js 및 TypeScript로 구축됨. 로컬 stdio(Claude Desktop) 및 원격 HTTP/SSE(Claude.ai Remote MCP) 모드를 모두 지원합니다.

⚠️ WhatsApp 서비스 약관 — 중요

이 프로젝트를 사용하기 전에 읽어보십시오.

WhatsApp의 서비스 약관 및 허용 가능한 사용 정책은 개인 또는 비즈니스 계정에서 비공식 자동화 도구 사용을 금지합니다.

🚫 번호가 차단될 수 있는 행동:

✅ 더 안전한 관행:

• 개인 번호가 아닌 전용/테스트용 전화번호를 사용하세요.

• 수신 동의를 한 연락처에만 메시지를 보내세요.

• 메시지 빈도를 낮게 유지하고 사람처럼 행동하세요.

• API_KEY 보호 없이 /sse 또는 REST 엔드포인트를 공개적으로 노출하지 마세요.

• 마케팅, 영업 홍보 또는 대규모 상업적 메시지 전송에 이 도구를 사용하지 마세요.

• 프로덕션/상업적 용도로는 WhatsApp Business API (공식)를 사용하세요.

🔒 이 프로젝트는 개인적인 자동화 및 개발/테스트 목적으로만 제작되었습니다. 작성자는 오용으로 인한 계정 차단이나 법적 결과에 대해 책임을 지지 않습니다.

Related MCP server: WhatsApp MCP Server

🗂️ 프로젝트 구조

whatsapp-mcp/
├── src/
│   ├── index.ts          # stdio MCP server (Claude Desktop)
│   ├── remote.ts         # HTTP/SSE MCP server (Remote MCP + REST API)
│   └── send_message.ts   # CLI script to send a single message
├── dist/                 # Compiled JavaScript (auto-generated, do not edit)
├── .wwebjs_auth/         # WhatsApp session data (⚠️ keep this gitignored!)
├── .wwebjs_cache/        # Puppeteer browser cache (gitignored)
├── package.json
├── tsconfig.json
├── render.yaml           # Render.com deployment config
├── start-remote.bat      # Windows quick-start script
└── README.md

🚀 빠른 시작

사전 요구 사항

• Node.js v18+ 및 npm

• WhatsApp 계정 (테스트 번호 사용!)

• Google Chrome 또는 Chromium 설치 (Puppeteer가 내부적으로 사용)

1. 종속성 설치

npm install

2. TypeScript 빌드

npm run build

3. 서버 시작

원격 HTTP/SSE 모드 (Claude.ai Remote MCP):

npm run start:remote

개발 모드 (빌드 불필요, ts-node 사용):

npm run dev:remote

stdio 모드 (Claude Desktop):

npm start

4. QR 코드 스캔

브라우저를 열고 다음으로 이동하세요:

http://localhost:3000/qr

WhatsApp으로 QR 코드를 스캔하세요 → 연결된 기기 → 기기 연결.

🔌 API 엔드포인트

🛠️ 사용 가능한 MCP 도구

🔐 선택 사항: Bearer 토큰 인증

API_KEY 환경 변수를 설정하여 REST 엔드포인트를 보호하세요:

API_KEY=mysecretkey npm run start:remote

모든 요청에 토큰을 포함하세요:

curl -H "Authorization: Bearer mysecretkey" http://localhost:3000/tools/status

🌐 ngrok을 사용한 테스트 (공개 HTTPS)

1. ngrok 설치

2. 서버 시작: npm run start:remote

3. 새 터미널에서: ngrok http 3000

4. 생성된 URL 복사 (예: https://xxxx.ngrok-free.app)

Claude.ai → 설정 → 통합 → 원격 MCP에 다음을 붙여넣으세요:

https://xxxx.ngrok-free.app/sse

☁️ Render에 배포

1. 이 저장소를 GitHub에 푸시 (아래 Git 단계 참조)

2. render.com으로 이동 → New → Web Service

3. GitHub 저장소 연결

4. 구성:

   • Build Command: npm install && npm run build

   • Start Command: npm run start:remote

   • Environment: NODE_ENV=production

   • Optional: API_KEY=yoursecretkey

5. 배포 후 https://your-app.onrender.com URL 복사

Claude Remote MCP에 붙여넣으세요:

https://your-app.onrender.com/sse

⚠️ 참고: WhatsApp 세션 데이터(.wwebjs_auth)는 Render 배포 간에 유지되지 않습니다. Render Disk를 사용하거나 배포할 때마다 QR 코드를 다시 스캔하세요.

📦 npm 스크립트

📄 .gitignore 권장 사항

.gitignore에 다음이 포함되어 있는지 확인하세요:

node_modules/
dist/
.wwebjs_auth/
.wwebjs_cache/
.env
*.bat

🔒 .wwebjs_auth/를 절대 커밋하지 마세요 — WhatsApp 세션 자격 증명이 포함되어 있습니다.

🔧 환경 변수

🤝 기여

풀 리퀘스트를 환영합니다! 주요 변경 사항의 경우 먼저 이슈를 열어주세요.

📜 라이선스

MIT — 책임감 있게, WhatsApp의 서비스 약관에 따라 사용하세요.

💡 팁: VS Code에 GitLens 확장 프로그램을 설치하면 커밋 기록, blame, 비교 등 훨씬 더 풍부한 Git 경험을 할 수 있습니다.