# verygoodplugins/whatsapp-mcp architecture

> Architecture diagram of the GitHub repository verygoodplugins/whatsapp-mcp, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-07). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/verygoodplugins/whatsapp-mcp
- Repository: https://github.com/verygoodplugins/whatsapp-mcp

## Overview

WhatsApp MCP exposes messaging tools to an MCP client, with a Python server calling a local Go bridge that maintains the WhatsApp session and local message history. The README documents this startup flow and the product’s messaging, media, read-receipt, call-history, and webhook capabilities. The sampled sources show MCP-to-client module references, media helpers, bridge authentication, history handling, and webhook delivery; unsampled handler wiring is represented only where documented.

Main entry points: [`whatsapp-mcp-server/main.py`](https://github.com/verygoodplugins/whatsapp-mcp/blob/main/whatsapp-mcp-server/main.py) (MCP tools), [`whatsapp-bridge/main.go`](https://github.com/verygoodplugins/whatsapp-mcp/blob/main/whatsapp-bridge/main.go) (WhatsApp runtime), [`whatsapp-mcp-server/whatsapp.py`](https://github.com/verygoodplugins/whatsapp-mcp/blob/main/whatsapp-mcp-server/whatsapp.py) (Bridge client), [`whatsapp-bridge/webhook.go`](https://github.com/verygoodplugins/whatsapp-mcp/blob/main/whatsapp-bridge/webhook.go) (Webhook delivery)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["MCP interface"]
  node_mcp_server["MCP tools<br/>[main.py]"]
  node_mcp_config["Transport config<br/>[mcp_config.py]"]
  node_watchdog["Parent watchdog<br/>[parent_watchdog.py]"]
end

subgraph group_access["WhatsApp access"]
  node_whatsapp_client["Bridge client<br/>[whatsapp.py]"]
  node_message_store[("Message store<br/>[main.go]")]
end

subgraph group_bridge["WhatsApp bridge"]
  node_bridge_runtime["WhatsApp runtime<br/>[main.go]"]
  node_bridge_auth["Bridge authentication<br/>[auth.go]"]
  node_history_sync["On-demand history"]
  node_webhook_delivery["Webhook delivery<br/>[webhook.go]"]
end

subgraph group_support["Media processing"]
  node_media_preview["Media previews<br/>[media_preview.py]"]
  node_transcription["Audio transcription<br/>[transcription.py]"]
  node_audio_convert["Audio conversion<br/>[audio.py]"]
end

node_mcp_user(("Claude or Cursor"))
node_whatsapp_network(("WhatsApp service"))
node_external_webhook(("Webhook receiver"))

node_mcp_user -->|"invokes tools"| node_mcp_server
node_mcp_server -->|"calls"| node_whatsapp_client
node_mcp_server -->|"configures transport"| node_mcp_config
node_mcp_server -->|"starts watchdog"| node_watchdog
node_whatsapp_client -->|"calls local API"| node_bridge_runtime
node_bridge_runtime -->|"loads token"| node_bridge_auth
node_bridge_runtime -->|"stores messages"| node_message_store
node_bridge_runtime -->|"connects session"| node_whatsapp_network
node_bridge_runtime -->|"serves history requests"| node_history_sync
node_bridge_runtime -->|"forwards messages"| node_webhook_delivery
node_webhook_delivery -->|"posts events"| node_external_webhook
node_mcp_server -->|"renders media"| node_media_preview
node_mcp_server -->|"transcribes audio"| node_transcription
node_whatsapp_client -->|"converts audio"| node_audio_convert
node_mcp_server -->|"reads local history"| node_message_store

click node_mcp_server "https://github.com/verygoodplugins/whatsapp-mcp/blob/main/whatsapp-mcp-server/main.py"
click node_mcp_config "https://github.com/verygoodplugins/whatsapp-mcp/blob/main/whatsapp-mcp-server/mcp_config.py"
click node_watchdog "https://github.com/verygoodplugins/whatsapp-mcp/blob/main/whatsapp-mcp-server/parent_watchdog.py"
click node_whatsapp_client "https://github.com/verygoodplugins/whatsapp-mcp/blob/main/whatsapp-mcp-server/whatsapp.py"
click node_message_store "https://github.com/verygoodplugins/whatsapp-mcp/blob/main/whatsapp-bridge/main.go"
click node_bridge_runtime "https://github.com/verygoodplugins/whatsapp-mcp/blob/main/whatsapp-bridge/main.go"
click node_bridge_auth "https://github.com/verygoodplugins/whatsapp-mcp/blob/main/whatsapp-bridge/auth.go"
click node_history_sync "https://github.com/verygoodplugins/whatsapp-mcp/blob/main/whatsapp-bridge/history_ondemand.go"
click node_webhook_delivery "https://github.com/verygoodplugins/whatsapp-mcp/blob/main/whatsapp-bridge/webhook.go"
click node_media_preview "https://github.com/verygoodplugins/whatsapp-mcp/blob/main/whatsapp-mcp-server/media_preview.py"
click node_transcription "https://github.com/verygoodplugins/whatsapp-mcp/blob/main/whatsapp-mcp-server/transcription.py"
click node_audio_convert "https://github.com/verygoodplugins/whatsapp-mcp/blob/main/whatsapp-mcp-server/audio.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_mcp_server,node_mcp_config,node_watchdog toneBlue
class node_whatsapp_client,node_message_store toneAmber
class node_bridge_runtime,node_bridge_auth,node_history_sync,node_webhook_delivery,node_external_webhook toneMint
class node_media_preview,node_transcription,node_audio_convert toneRose
class node_mcp_user,node_whatsapp_network toneIndigo
```

## Components

### MCP interface

- [MCP tools](https://github.com/verygoodplugins/whatsapp-mcp/blob/main/whatsapp-mcp-server/main.py): `whatsapp-mcp-server/main.py`
- [Transport config](https://github.com/verygoodplugins/whatsapp-mcp/blob/main/whatsapp-mcp-server/mcp_config.py): `whatsapp-mcp-server/mcp_config.py`
- [Parent watchdog](https://github.com/verygoodplugins/whatsapp-mcp/blob/main/whatsapp-mcp-server/parent_watchdog.py): `whatsapp-mcp-server/parent_watchdog.py`

### WhatsApp access

- [Bridge client](https://github.com/verygoodplugins/whatsapp-mcp/blob/main/whatsapp-mcp-server/whatsapp.py): `whatsapp-mcp-server/whatsapp.py`
- [Message store](https://github.com/verygoodplugins/whatsapp-mcp/blob/main/whatsapp-bridge/main.go): `whatsapp-bridge/main.go`

### WhatsApp bridge

- [WhatsApp runtime](https://github.com/verygoodplugins/whatsapp-mcp/blob/main/whatsapp-bridge/main.go): `whatsapp-bridge/main.go`
- [Bridge authentication](https://github.com/verygoodplugins/whatsapp-mcp/blob/main/whatsapp-bridge/auth.go): `whatsapp-bridge/auth.go`
- [On-demand history](https://github.com/verygoodplugins/whatsapp-mcp/blob/main/whatsapp-bridge/history_ondemand.go): `whatsapp-bridge/history_ondemand.go`
- [Webhook delivery](https://github.com/verygoodplugins/whatsapp-mcp/blob/main/whatsapp-bridge/webhook.go): `whatsapp-bridge/webhook.go`

### Media processing

- [Media previews](https://github.com/verygoodplugins/whatsapp-mcp/blob/main/whatsapp-mcp-server/media_preview.py): `whatsapp-mcp-server/media_preview.py`
- [Audio transcription](https://github.com/verygoodplugins/whatsapp-mcp/blob/main/whatsapp-mcp-server/transcription.py): `whatsapp-mcp-server/transcription.py`
- [Audio conversion](https://github.com/verygoodplugins/whatsapp-mcp/blob/main/whatsapp-mcp-server/audio.py): `whatsapp-mcp-server/audio.py`

### Other components

- **Claude or Cursor**
- **WhatsApp service**
- **Webhook receiver**

## Connections

- Claude or Cursor → MCP tools: invokes tools (evidence: `README.md`)
- MCP tools → Bridge client: calls (evidence: `whatsapp-mcp-server/main.py`)
- MCP tools → Transport config: configures transport (evidence: `whatsapp-mcp-server/main.py`)
- MCP tools → Parent watchdog: starts watchdog (evidence: `whatsapp-mcp-server/main.py`)
- Bridge client → WhatsApp runtime: calls local API (evidence: `README.md`)
- WhatsApp runtime → Bridge authentication: loads token (evidence: `whatsapp-bridge/main.go`)
- WhatsApp runtime → Message store: stores messages (evidence: `README.md`)
- WhatsApp runtime → WhatsApp service: connects session (evidence: `README.md`)
- WhatsApp runtime → On-demand history: serves history requests (evidence: `whatsapp-bridge/history_ondemand.go`)
- WhatsApp runtime → Webhook delivery: forwards messages (evidence: `whatsapp-bridge/webhook.go`)
- Webhook delivery → Webhook receiver: posts events (evidence: `whatsapp-bridge/webhook.go`)
- MCP tools → Media previews: renders media (evidence: `whatsapp-mcp-server/main.py`)
- MCP tools → Audio transcription: transcribes audio (evidence: `whatsapp-mcp-server/main.py`)
- Bridge client → Audio conversion: converts audio (evidence: `whatsapp-mcp-server/whatsapp.py`)
- MCP tools → Message store: reads local history (evidence: `README.md`)
