<<<<<<< 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)