📱 WhatsApp MCP — Remote HTTP/SSE Server

Model Context Protocol (MCP) server for WhatsApp, built with whatsapp-web.js and TypeScript.
Supports both local stdio (Claude Desktop) and remote HTTP/SSE (Claude.ai Remote MCP) modes.

---

⚠️ WhatsApp Terms of Service — IMPORTANT

Read this before using this project.

WhatsApp's Terms of Service and Acceptable Use Policy prohibit the use of unofficial automation tools on personal or business accounts.

🚫 Actions that will get your number BANNED:

Violation	Risk Level
Sending bulk/spam messages	🔴 Instant Ban
Automating messages to unknown numbers	🔴 Instant Ban
Using unofficial WhatsApp clients (like whatsapp-web.js)	🟠 High Risk
Scraping contacts or group data at scale	🟠 High Risk
Sending messages without user consent	🔴 Instant Ban
Running the bot 24/7 on a personal number	🟡 Medium Risk
Sending media/files in bulk	🟠 High Risk

✅ Safer Practices:

• Use a dedicated/test phone number, not your personal number
• Only message contacts who have opted in
• Keep message frequency low and human-like
• Do not expose your /sse or REST endpoints publicly without API_KEY protection
• Do not use this for marketing, sales blasting, or any commercial messaging at scale
• Use WhatsApp Business API (Official) for production/commercial use

🔒 This project is intended for personal automation and development/testing only.
The author is not responsible for any account bans or legal consequences resulting from misuse.

---

🗂️ Project Structure

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

---

🚀 Quick Start

Prerequisites

• Node.js v18+ and npm
• A WhatsApp account (use a test number!)
• Google Chrome or Chromium installed (used by Puppeteer internally)

---

1. Install Dependencies

npm install

---

2. Build TypeScript

npm run build

---

3. Start the Server

Remote HTTP/SSE mode (Claude.ai Remote MCP):

npm run start:remote

Dev mode (no build needed, uses ts-node):

npm run dev:remote

stdio mode (Claude Desktop):

npm start

---

4. Scan the QR Code

Open your browser and go to:

http://localhost:3000/qr

Scan the QR code with WhatsApp → Linked Devices → Link a Device.

---

🔌 API Endpoints

Method	Path	Description
GET	/ or /health	Health check + WhatsApp status
GET	/qr	QR code HTML page (scan to authenticate)
GET	/qr?format=json	Raw QR data in JSON
GET	/tools	List all available MCP tools
GET	/tools/status	WhatsApp connection status
POST	/tools/send-message	Send a WhatsApp message
GET	/tools/chats	List recent chats
GET	/tools/contacts	List contacts
GET	/tools/messages/:chatId	Fetch messages from a chat
POST	/tools/invoke	Generic MCP tool invocation
GET	/sse	MCP SSE endpoint (Claude Remote MCP)
POST	/messages	MCP POST endpoint (paired with /sse)

---

🛠️ Available MCP Tools

Tool	Description
whatsapp_status	Check connection status
whatsapp_send_message	Send a text message
whatsapp_send_media	Send image / video / document
whatsapp_get_contacts	List all contacts
whatsapp_get_groups	List all groups
whatsapp_get_group_info	Get group details and members
whatsapp_create_group	Create a new group
whatsapp_get_chats	Get recent chats
whatsapp_get_messages	Get messages from a specific chat

---

🔐 Optional: Bearer Token Auth

Protect your REST endpoints by setting an API_KEY environment variable:

API_KEY=mysecretkey npm run start:remote

Include the token in all requests:

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

---

🌐 Testing with ngrok (Public HTTPS)

1. Install ngrok
2. Start your server: npm run start:remote
3. In a new terminal: ngrok http 3000
4. Copy the generated URL (e.g., https://xxxx.ngrok-free.app)

In Claude.ai → Settings → Integrations → Remote MCP, paste:

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

---

☁️ Deploy to Render

1. Push this repo to GitHub (see Git steps below)
2. Go to render.com → New → Web Service
3. Connect your GitHub repository
4. Configure:
   • Build Command: npm install && npm run build
   • Start Command: npm run start:remote
   • Environment: NODE_ENV=production
   • Optional: API_KEY=yoursecretkey
5. Deploy and copy your https://your-app.onrender.com URL

Paste into Claude Remote MCP:

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

⚠️ Note: WhatsApp session data (.wwebjs_auth) does not persist across Render deploys. Use a Render Disk or re-scan the QR code after each deploy.

---

📦 npm Scripts

Command	Description
npm run build	Compile TypeScript to dist/
npm start	Start stdio MCP server
npm run start:remote	Start HTTP/SSE remote server
npm run dev	Dev stdio server (ts-node, no build)
npm run dev:remote	Dev remote server (ts-node, no build)
npm run send	CLI: send a single message
npm run qr	Show QR code in terminal

---

📄 .gitignore Recommendations

Make sure your .gitignore includes:

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

🔒 Never commit .wwebjs_auth/ — it contains your WhatsApp session credentials.

---

🔧 Environment Variables

Variable	Default	Description
PORT	3000	HTTP server port
HOST	0.0.0.0	Server bind address
API_KEY	(empty)	Optional Bearer token for REST auth
NODE_ENV	development	Set to production on Render

---

🤝 Contributing

Pull requests are welcome! For major changes, please open an issue first.

---

📜 License

MIT — use responsibly and in accordance with WhatsApp's Terms of Service.

---

💡 Tip: Install the GitLens extension in VS Code for a much richer Git experience — commit history, blame, comparisons and more.