@clickonsearch/whatsapp-mcp-server 0.1.0 → 0.1.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +61 -49
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,72 +1,84 @@
|
|
|
1
1
|
# @clickonsearch/whatsapp-mcp-server
|
|
2
2
|
|
|
3
|
-
|
|
4
|
-
does — scan a QR code,
|
|
5
|
-
[
|
|
6
|
-
|
|
7
|
-
`search_contacts`, plus a plain SSE stream of incoming messages for anything
|
|
8
|
-
that wants to react to them live.
|
|
3
|
+
Links a personal WhatsApp account to this repo's agents, the same way
|
|
4
|
+
WhatsApp Web does — scan a QR code once, it stays connected. Usually you
|
|
5
|
+
won't run this directly; [`whatsapp-agent`](../../agents/whatsapp-agent)'s
|
|
6
|
+
README tells you when to start it.
|
|
9
7
|
|
|
10
|
-
> **
|
|
11
|
-
> library
|
|
12
|
-
>
|
|
13
|
-
>
|
|
8
|
+
> **Heads up:** this isn't the official WhatsApp Business API — it's an
|
|
9
|
+
> unofficial library ([Baileys](https://github.com/WhiskeySockets/Baileys))
|
|
10
|
+
> automating a personal account, which WhatsApp's terms don't really
|
|
11
|
+
> cover. Risk is low for normal personal use, but there's a small chance of
|
|
12
|
+
> the account getting flagged.
|
|
14
13
|
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
14
|
+
```
|
|
15
|
+
whatsapp-agent (or any MCP client)
|
|
16
|
+
│
|
|
17
|
+
▼
|
|
18
|
+
┌─────────────────────────────┐
|
|
19
|
+
│ whatsapp-mcp-server │ Streamable HTTP MCP
|
|
20
|
+
└──────────────┬──────────────┘
|
|
21
|
+
│
|
|
22
|
+
▼
|
|
23
|
+
┌─────────────────────────────┐
|
|
24
|
+
│ Baileys │ WhatsApp Web protocol
|
|
25
|
+
└──────────────┬──────────────┘
|
|
26
|
+
│
|
|
27
|
+
▼
|
|
28
|
+
your WhatsApp account
|
|
30
29
|
```
|
|
31
30
|
|
|
32
31
|
## Run
|
|
33
32
|
|
|
34
33
|
```bash
|
|
35
|
-
|
|
34
|
+
npx @clickonsearch/whatsapp-mcp-server
|
|
36
35
|
```
|
|
37
36
|
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
Once connected:
|
|
37
|
+
The first time, it prints a QR code — scan it with your phone: **WhatsApp →
|
|
38
|
+
Settings → Linked devices → Link a device**. After that it reconnects
|
|
39
|
+
automatically, no need to scan again (unless you unlink the device from
|
|
40
|
+
your phone).
|
|
44
41
|
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
message: `{ chatId, fromMe, senderName, text, timestamp }`.
|
|
49
|
-
- `GET http://localhost:4100/health` — `{ ok, connected, self }`, where
|
|
50
|
-
`self` is your own normalized JID once connected.
|
|
42
|
+
Once connected, it's listening on `http://localhost:4100` for whatever
|
|
43
|
+
agent you point at it. No environment variables are required to try it —
|
|
44
|
+
everything below has a default.
|
|
51
45
|
|
|
52
|
-
## Config
|
|
46
|
+
## Config reference
|
|
53
47
|
|
|
54
48
|
| Env var | Default | Notes |
|
|
55
49
|
| -------------------- | ------------------ | ---------------------------------------------- |
|
|
56
50
|
| `PORT` | `4100` | |
|
|
57
|
-
| `WHATSAPP_AUTH_DIR` | `./whatsapp-auth` | Your session — never commit this
|
|
58
|
-
| `BAILEYS_LOG_LEVEL` | `silent` | `info
|
|
51
|
+
| `WHATSAPP_AUTH_DIR` | `./whatsapp-auth` | Your session — never share or commit this folder |
|
|
52
|
+
| `BAILEYS_LOG_LEVEL` | `silent` | Set to `info` or `debug` to see connection details |
|
|
59
53
|
|
|
60
|
-
##
|
|
54
|
+
## What it exposes
|
|
61
55
|
|
|
62
|
-
| Tool |
|
|
63
|
-
| ---------------------- |
|
|
64
|
-
| `send_message` |
|
|
65
|
-
| `list_chats` |
|
|
66
|
-
| `get_recent_messages` |
|
|
67
|
-
| `search_contacts` |
|
|
56
|
+
| Tool | What it does |
|
|
57
|
+
| ---------------------- | --------------------------------------- |
|
|
58
|
+
| `send_message` | Sends a text message to a phone number or chat |
|
|
59
|
+
| `list_chats` | Lists chats seen since connecting (includes WhatsApp's own recent history) |
|
|
60
|
+
| `get_recent_messages` | Gets recent messages from one chat (up to 200, in memory only) |
|
|
61
|
+
| `search_contacts` | Finds a contact by name or number |
|
|
62
|
+
|
|
63
|
+
---
|
|
64
|
+
|
|
65
|
+
## For developers
|
|
66
|
+
|
|
67
|
+
**Running from source:**
|
|
68
|
+
|
|
69
|
+
```bash
|
|
70
|
+
cd mcp-servers/whatsapp-mcp-server
|
|
71
|
+
npm install
|
|
72
|
+
cp .env.example .env
|
|
73
|
+
npm run dev
|
|
74
|
+
```
|
|
68
75
|
|
|
69
|
-
|
|
76
|
+
This runs as a standard MCP server (Streamable HTTP on `/mcp`), so any of
|
|
77
|
+
this repo's bridges can connect to it with no special-casing — it just had
|
|
78
|
+
to speak the same protocol GitHub's own remote MCP server does. It also
|
|
79
|
+
exposes `GET /events` (a plain SSE stream of incoming messages) and
|
|
80
|
+
`GET /health` (`{ ok, connected, self }`) for anything that wants to react
|
|
81
|
+
to messages live, like `whatsapp-agent` does.
|
|
70
82
|
|
|
71
83
|
```ts
|
|
72
84
|
import { WhatsAppConnection } from "./src/whatsapp.js";
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@clickonsearch/whatsapp-mcp-server",
|
|
3
|
-
"version": "0.1.
|
|
3
|
+
"version": "0.1.1",
|
|
4
4
|
"description": "MCP server that connects to a personal WhatsApp account (via Baileys) and exposes it as tools — send messages, list chats, read recent messages, search contacts — plus an SSE stream of incoming messages.",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"license": "MIT",
|