# WhatsApp Web MCP

A local MCP server for reading authorized WhatsApp conversations, retrieving media,
exporting bounded history and preparing confirmation-gated messages. Its 13 typed
tools expose chats and messages rather than browser controls. OpenWA owns the
WhatsApp Web connection; optional local processors handle audio, images and documents.

## Read, inspect, then act

For a known conversation, call `whatsapp_get_messages` directly. Use
`whatsapp_find` to discover a contact or search within a specified conversation.
History exports include coverage information: a partial result is identified as
partial, with its stopping condition, rather than presented as a complete archive.

Sending is a separate stateful operation. `whatsapp_send_message` prepares a
preview, target and action ID. Confirmation requires the literal phrase returned
by that preview and the user's explicit instruction. An action is claimed once.
After dispatch, the server reloads the message before reporting `sent: true`.
An ambiguous result consumes the action and returns `delivery_unconfirmed`;
it is not retried automatically. Reloading proves that the backend can retrieve
the outgoing message, not that its recipient has read it.

## Tools

| Purpose | Tools |
| --- | --- |
| Connection and discovery | `whatsapp_status`, `whatsapp_list_chats`, `whatsapp_find` |
| Identity and context | `whatsapp_get_contact`, `whatsapp_get_chat_info` |
| Conversation content | `whatsapp_get_message`, `whatsapp_get_messages`, `whatsapp_get_chat` |
| Media | `whatsapp_get_media`, `whatsapp_understand` |
| State and actions | `whatsapp_send_message`, `whatsapp_jobs`, `whatsapp_settings` |

Each tool accepts a typed `request` object. Public identifiers hide backend JIDs
and session configuration. See [request models](whatsapp_web_mcp/v1_models.py)
and [tool registration](server.py) for the current contract.

## Installation

Requires Python 3.11+, Node.js/npm and a Chrome/Chromium installation for OpenWA.
FFmpeg and the `transcription` extra support audio/video; Tesseract, Poppler and
LibreOffice support applicable OCR/document formats.

```bash
git clone https://github.com/KingDonRush/whatsapp-web-mcp.git
cd whatsapp-web-mcp
python3 -m venv .venv
. .venv/bin/activate
python -m pip install -e .
whatsapp-web-mcp doctor
whatsapp-web-mcp auth --profile default
whatsapp-web-mcp serve
```

Authentication installs exactly `@open-wa/wa-automate@4.76.0` in the private data
directory and applies the compatibility patches in
[openwa_runtime.py](whatsapp_web_mcp/openwa_runtime.py). Authentication displays
a local QR page; the MCP does not return the QR. Subsequent operations are headless.
Use `auth --no-open` when the browser must be opened separately in a secure local
or tunneled environment. Keep the OpenWA HTTP service on loopback.

Configure an MCP client to run the virtual environment's `whatsapp-web-mcp` executable
with `args: ["serve"]`. Set `WHATSAPP_MCP_DATA_DIR` to an absolute persistent
private directory and `WHATSAPP_MCP_PROFILE` to the intended profile before starting.
The default data directory is `~/.local/share/whatsapp-web-mcp`.

## Examples

Read the newest audio or voice note from a known chat:

```json
{"request":{"chat_id":"c_12345678","types":["audio"],"period":"últimos 7 dias","limit":1}}
```

Pass its returned `message_id` to `whatsapp_understand` to fetch the original media
and process it. Date expressions accept ISO dates and supported Brazilian Portuguese
periods; see [date parsing](whatsapp_web_mcp/date_ranges.py). Tool prompts and natural
period parsing currently favor Portuguese, while the transport and schemas are language independent.

Export an explicitly selected conversation:

```json
{"request":{"selector":"Example project group","period":"março de 2026"}}
```

## Architecture and boundaries

The stdio entry point delegates to domain services. OpenWA access, history loading,
media processing, artifact generation, ID registration and action persistence have
separate modules. JSON records use private atomic writes; action claims use atomic
renames to prevent duplicate dispatch. Path-bearing action/job identifiers are
validated before accessing local files.

- This is an unofficial WhatsApp Web integration. Upstream browser/API changes can
  break compatibility; the pinned runtime and its patches need maintenance.
- Runtime profiles separate browser authentication. Run separate MCP processes with
  distinct data directories for separate users; domain artifacts are local process data.
- Job listing/cancellation and repeat records exist; there is no general background
  worker consuming the repeat queue. A queued record is not completed work.
- History completeness depends on what WhatsApp exposes. OCR/transcription quality
  depends on installed tools, models and source media.
- Local data includes conversation content, media, credentials and diagnostics.
  It stays outside source control. See [SECURITY.md](SECURITY.md).

## Verification

```bash
python -m unittest discover -s tests -v
python -m compileall server.py whatsapp_web_mcp tests
```

The offline suite covers tool schemas, date ranges, history boundaries, media,
action confirmation/replay, backend verification, private persistence and path
traversal. Live read/send smoke tests are opt-in and skipped by default. They need
an authenticated session and an explicitly configured test group; sending also
requires a separate confirmation flag. Offline passing tests do not establish
current live WhatsApp compatibility. No live messages were sent in this verification pass.

[MIT license](LICENSE).