📱 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.