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

Install ngrok: https://ngrok.com/download
Start your server: npm run start:remote
In a new terminal: ngrok http 3000
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

Push this repo to GitHub
Go to https://render.com → New → Web Service
Connect your repo
Set:
- Build Command: npm install && npm run build
- Start Command: npm run start:remote
- Environment: NODE_ENV=production
- Optional: API_KEY=yoursecretkey
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)

WhatsApp MCP