Skip to content
Back to search

whatsapp-mcp-ha

Home Assistant add-on: your personal WhatsApp account (linked device, whatsmeow) as an MCP server over streamable HTTP with a bearer token

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/jpch--whatsapp-mcp-ha/badge.svg)](/listings/jpch--whatsapp-mcp-ha)

HTML

<a href="/listings/jpch--whatsapp-mcp-ha"><img src="/api/listings/jpch--whatsapp-mcp-ha/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

1. **Settings → Add-ons → Add-on store → ⋮ → Repositories**, add `https://github.com/jpch/whatsapp-mcp-ha`. 2. Install **WhatsApp MCP**. The first install builds the image on the device and takes a few minutes. 3. In **Configuration**, optional: set `auth_token`, the read-only token (32+ random printable characters, e.g. `openssl rand -base64 32`). If you leave it empty, the add-on generates one and shows it **once** on its page. Sending is off by default; see [Sending](#sending). 4. **Start** the add-on and open **Open Web UI** (or the sidebar entry **WhatsApp MCP**, administrators only). 5. On your phone: **WhatsApp → Settings → Linked devices → Link a device**, and scan the QR code shown on the page. The page shows **Connected** when done. In the add-on the QR code is only on the page, never in the log.

A watchdog restarts the add-on if the endpoint stops answering. An invalid configuration stops the add-on with the error in the log instead of restarting it.

If the QR codes expire, press **Show a new QR code** on the page (or restart the add-on). If WhatsApp unlinks the device (from the phone, or after a long time offline), the add-on goes back to showing a QR code. **Unlink this device** on the page logs out and starts a new pairing.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 159 lines
  1. # WhatsApp MCP add-on for Home Assistant
  2. A Home Assistant add-on that links **your personal WhatsApp account as a device** (the same mechanism as WhatsApp
  3. Web, through [whatsmeow](https://github.com/tulir/whatsmeow)) and exposes it as an **MCP server over streamable
  4. HTTP**, so AI agents can search and read your chats and, if you allow it, send messages and files.
  5. - Personal use only. It does **not** use the WhatsApp Business API. Unofficial clients are against WhatsApp's
  6. terms of service and can get a number restricted; use it at your own risk and keep sending volumes low.
  7. - One Go binary: the whatsmeow client, the local message store and the MCP server. There is no separate bridge
  8. REST API, so nothing besides `/mcp` and `/healthz` listens on the exposed port.
  9. - Session and messages are stored in the add-on's `/data` (included in Home Assistant backups).
  10. Independent project, not affiliated with WhatsApp or Meta. The tool set and message store are derived from
  11. [lharries/whatsapp-mcp](https://github.com/lharries/whatsapp-mcp) (MIT).
  12. ## Install (Home Assistant OS, aarch64 or amd64)
  13. 1. **Settings → Add-ons → Add-on store → ⋮ → Repositories**, add `https://github.com/jpch/whatsapp-mcp-ha`.
  14. 2. Install **WhatsApp MCP**. The first install builds the image on the device and takes a few minutes.
  15. 3. In **Configuration**, optional: set `auth_token`, the read-only token (32+ random printable characters, e.g.
  16. `openssl rand -base64 32`). If you leave it empty, the add-on generates one and shows it **once** on its page.
  17. Sending is off by default; see [Sending](#sending).
  18. 4. **Start** the add-on and open **Open Web UI** (or the sidebar entry **WhatsApp MCP**, administrators only).
  19. 5. On your phone: **WhatsApp → Settings → Linked devices → Link a device**, and scan the QR code shown on the page.
  20. The page shows **Connected** when done. In the add-on the QR code is only on the page, never in the log.
  21. A watchdog restarts the add-on if the endpoint stops answering. An invalid configuration stops the add-on with
  22. the error in the log instead of restarting it.
  23. If the QR codes expire, press **Show a new QR code** on the page (or restart the add-on). If WhatsApp unlinks the
  24. device (from the phone, or after a long time offline), the add-on goes back to showing a QR code. **Unlink this
  25. device** on the page logs out and starts a new pairing.
  26. ## Connect an MCP client
  27. | | |
  28. |---|---|
  29. | Transport | streamable HTTP (stateless, JSON responses) |
  30. | Path | `/mcp` |
  31. | Port | `8120` (container port) |
  32. | From other add-ons (e.g. cloudflared) | `http://2b052fb0-whatsapp-mcp:8120/mcp` |
  33. | Header | `Authorization: Bearer <token>` (`auth_token`: read tools; `send_token`: read and send tools) |
  34. The hostname is `<repository hash>-whatsapp-mcp`; the hash is `2b052fb0` when the repository was added as
  35. `https://github.com/jpch/whatsapp-mcp-ha`. The add-on page shows the exact internal URL.
  36. The port is **not published on the host** by default. To use it from the LAN, set a host port under
  37. **Configuration → Network**. To use it from outside, put a tunnel in front (e.g. a Cloudflare Tunnel with the
  38. internal URL above as the service). Cloudflare Access and the bearer token are separate layers: Access decides who
  39. reaches the hostname, the bearer token decides what the caller may do. Keep both. Do not forward the port on your
  40. router.
  41. ```json
  42. { "mcpServers": { "whatsapp": { "type": "http", "url": "https://<your-hostname>/mcp",
  43. "headers": { "Authorization": "Bearer <token>" } } } }
  44. ```
  45. `GET /healthz` answers `{"status":"ok"}` without authentication and without any other detail.
  46. ## Tools
  47. | Tool | |
  48. |---|---|
  49. | `get_status` | connection state, limits, outbox folder |
  50. | `search_contacts` | by name or number (address book synced from the phone, plus known chats) |
  51. | `list_chats`, `get_chat`, `get_direct_chat_by_contact`, `get_contact_chats` | chats |
  52. | `list_messages`, `get_message_context`, `get_last_interaction` | messages (search, filters, context) |
  53. | `send_message` | send token only: text to a phone number (country code, digits only) or a JID (`…@s.whatsapp.net`, `…@lid`, group `…@g.us`) |
  54. | `send_file` | send token only: image, video, audio or document **from the outbox folder only** |
  55. | `send_audio_message` | send token only: an Ogg Opus `.ogg` file from the outbox as a voice note |
  56. | `download_media` | only when `allow_media_download` is on; saves into `/share/whatsapp-mcp/downloads` |
  57. Message text, captions, file names and contact, chat and group names are returned inside an `untrusted` object
  58. in every result, so agents can tell other people's words from data they may act on.
  59. Only messages received while the add-on runs, plus what WhatsApp sends in the history sync after pairing, are
  60. searchable.
  61. Limitations: edits, deletions ("deleted for everyone") and reactions are not applied to stored messages;
  62. voice notes must already be Ogg Opus (no ffmpeg in the image); passkey pairing is not supported (use the QR code).
  63. ## Configuration
  64. | Option | Default | |
  65. |---|---|---|
  66. | `auth_token` | empty | read-only bearer token; empty = generated, shown once on the add-on page |
  67. | `send_token` | empty | the only token that gets the send tools (when `enable_send` is on); must differ from `auth_token`; empty = generated, shown once on the add-on page |
  68. | `enable_send` | `false` | `true` adds the send tools for the send token |
  69. | `send_rate_per_minute` | `6` | sends per minute, all clients together |
  70. | `send_daily_limit` | `50` | sends per rolling 24 hours |
  71. | `allowed_recipients` | empty (no sends) | phone numbers (country code, digits) or JIDs the send tools may write to |
  72. | `allow_media_download` | `false` | enables `download_media` |
  73. | `max_media_mb` | `16` | largest file sent or downloaded (also caps media downloads from WhatsApp's servers) |
  74. | `retention_days` | `0` | delete stored messages older than this; `0` keeps everything |
  75. | `log_level` | `info` | message contents and tokens are never logged; other people's numbers and JIDs are masked |
  76. ## Sending
  77. 1. Set `enable_send: true`.
  78. 2. Set `allowed_recipients`, e.g. `+351900000000` or `120363000000000000@g.us`. Empty refuses every send.
  79. 3. Set `send_token` (32+ random characters, different from `auth_token`), or leave it empty and copy the generated
  80. one from the add-on page (shown once; **Generate a new send token** replaces it). A `send_token` set in the
  81. configuration is never shown or replaced from the page, which is the safer choice.
  82. 4. Give the send token **only** to the one client that should send. Never put it into a shared or portal client;
  83. those keep using `auth_token`, which never sees the send tools.
  84. `allowed_recipients` is compared with the recipient exactly as the agent passes it (normalised to a JID): a phone
  85. number allows `…@s.whatsapp.net`; if a contact is addressed by its `…@lid` JID, list that form as well.
  86. **Sending files:** copy them to `/share/whatsapp-mcp/outbox/` (e.g. with the Samba or File editor add-on) and pass
  87. the file name as `media_path`. Paths outside that folder, `..` and symlinks pointing out of it are refused.
  88. ## Plain Docker (e.g. a NAS)
  89. ```sh
  90. git clone https://github.com/jpch/whatsapp-mcp-ha && cd whatsapp-mcp-ha
  91. docker build -t whatsapp-mcp --build-arg BUILD_FROM=ghcr.io/home-assistant/amd64-base:3.24 whatsapp_mcp
  92. docker run -d --name whatsapp-mcp --restart unless-stopped \
  93. -p 8120:8120 \
  94. -v "$PWD/data:/data" -v "$PWD/media:/share/whatsapp-mcp" \
  95. -e WA_MCP_TOKEN="<32+ random characters>" \
  96. whatsapp-mcp
  97. docker logs -f whatsapp-mcp # no pairing page in plain Docker: scan the QR code printed here
  98. ```
  99. Use `aarch64-base` on ARM. Without `WA_MCP_TOKEN` a token is generated into `data/auth_token`. Other variables:
  100. `WA_MCP_ENABLE_SEND`, `WA_MCP_SEND_TOKEN` (generated into `data/send_token` when sending is on and it is unset), `WA_MCP_SEND_RATE_PER_MINUTE`, `WA_MCP_SEND_DAILY_LIMIT`, `WA_MCP_ALLOW_MEDIA_DOWNLOAD`,
  101. `WA_MCP_MAX_MEDIA_MB`, `WA_MCP_LOG_LEVEL`, `WA_MCP_ALLOWED_RECIPIENTS` (comma-separated), `WA_MCP_RETENTION_DAYS`. The pairing page is off in plain Docker (it has no login of its own).
  102. To re-pair after an unlink, run `docker restart whatsapp-mcp` and scan the new code from the log.
  103. ## Security
  104. See [SECURITY.md](SECURITY.md) and [docs/security-review.md](docs/security-review.md). In short: bearer tokens
  105. required (constant-time check, failed attempts throttled), read-only unless you enable sending, send tools only for
  106. a separate send token, sends limited to `allowed_recipients` and rate limited, file sending confined to the outbox,
  107. received file names sanitised and never overwriting files, media download off by default, no other routes on the
  108. exposed port, pairing page only through Home Assistant ingress for administrators, message contents and tokens never
  109. logged, other people's numbers masked in logs, data folder `0700` and session, message, token and media files `0600`.
  110. **Warning: prompt injection.** Anyone who can message you can write text that tries to make an agent send
  111. messages or files on your behalf. An agent that can read your messages and also send is the risky combination.
  112. Keep sending off unless you need it; if you enable it, keep `allowed_recipients` short, keep the send limits low,
  113. keep only files you are happy to share in the outbox, and prefer agents that ask you before sending.
  114. **Unofficial client.** whatsmeow is not an official WhatsApp client. WhatsApp can restrict or ban numbers that use
  115. it; a secondary number reduces the impact.
  116. **Rotating tokens.** Changing `auth_token` (or generating a new one on the page) means updating every client that
  117. stores it, e.g. MCP portals or connectors. The same applies to `send_token` for the client that sends.
  118. **Generated token and other add-ons.** All Home Assistant ingress pages share one browser origin, so a page of
  119. another add-on that you open could call this add-on's page too. That is why a generated token is shown only once
  120. (and can only be replaced afterwards). Setting your own `auth_token` avoids showing it at all.
  121. Writes of the server process are confined by an AppArmor profile to `/data` and `/share/whatsapp-mcp`.
  122. ## License
  123. MIT, see [LICENSE](LICENSE). whatsmeow is MPL-2.0 (used unmodified as a Go module).

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.