<<<<<<< HEAD

whatsapp_MCP

=======

WhatsApp MCP — Remote HTTP Server

A Model Context Protocol (MCP) server for WhatsApp built with whatsapp-web.js.
Supports two modes:

Mode	File	Use case
stdio	src/index.ts	Claude Desktop (local)
Remote HTTP/SSE	src/remote.ts	Claude.ai "Remote MCP URL" / any HTTP client

---

Quick Start

1. Install dependencies

npm install

2. Build TypeScript

npm run build

3. Run the remote server

npm run start:remote
# or in dev mode (no build needed):
npm run dev:remote

4. Scan the QR code

Open http://localhost:3000/qr in your browser and scan with WhatsApp → Linked Devices.

---

Endpoints

Method	Path	Description
GET	/ or /health	Health check + status
GET	/qr	QR code page (browser) or ?format=json for raw data
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 tool invocation
GET	/sse	MCP SSE endpoint (for Claude Remote MCP)
POST	/messages	MCP POST endpoint (used with /sse)

---

REST API Examples

Check status

curl http://localhost:3000/tools/status

Send a message

curl -X POST http://localhost:3000/tools/send-message \
  -H "Content-Type: application/json" \
  -d '{"to": "919876543210", "message": "Hello from MCP!"}'

Get recent chats

curl "http://localhost:3000/tools/chats?limit=10"

Get messages from a chat

curl "http://localhost:3000/tools/messages/919876543210?limit=20"

Generic tool invocation

curl -X POST http://localhost:3000/tools/invoke \
  -H "Content-Type: application/json" \
  -d '{"tool": "whatsapp_get_groups", "args": {}}'

---

Optional: Bearer Token Auth

Set the API_KEY environment variable to protect REST endpoints:

API_KEY=mysecretkey npm run start:remote

Then include the header in requests:

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

---

Testing with ngrok (public HTTPS URL)

1. Install ngrok: https://ngrok.com/download
2. Start your server: npm run start:remote
3. In a new terminal: ngrok http 3000
4. Copy the https://xxxx.ngrok-free.app URL

Paste this into Claude → Settings → Integrations → Remote MCP:

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

---

Deploy to Render

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

Paste into Claude Remote MCP:

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

⚠️ Important for Render: WhatsApp session data (.wwebjs_auth) does not persist across Render deploys by default. Use a Render Disk (persistent storage) or re-scan the QR after each deploy. See Render Disks.

---

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 message
├── dist/                 # Compiled JS (after npm run build)
├── .wwebjs_auth/         # WhatsApp session data (gitignore this!)
├── package.json
├── tsconfig.json
└── README.md

---

Available MCP Tools

Tool	Description
whatsapp_status	Check connection status
whatsapp_send_message	Send a text message
whatsapp_send_media	Send image/video/doc
whatsapp_get_contacts	List contacts
whatsapp_get_groups	List groups
whatsapp_get_group_info	Group details + members
whatsapp_create_group	Create a new group
whatsapp_get_chats	Recent chats
whatsapp_get_messages	Messages from a chat

---

.gitignore recommendations

node_modules/
dist/
.wwebjs_auth/
.wwebjs_cache/
.env

2848b1a (whatsapp mcp)