convez.ai
MCP ServerIntegração & APIsAvançado
asimzeeshan

WhatsApp Bridge MCP

asimzeeshan/WhatsApp-bridge

Integre WhatsApp nativamente ao Claude com busca semântica e transcrição

Ver no GitHub
InicialPluginScore · de 0 a 100

Servidor MCP em produção que conecta Claude e aplicações de IA ao WhatsApp via protocolo nativo. Permite enviar mensagens, reagir, editar, deletar, monitorar grupos, busca semântica, download de mídia e transcrição de áudios com arquitetura robusta em Go + Python.

Instalação

$npx convez-ai asimzeeshan/WhatsApp-bridge

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
0
Forks
1
Acompanhando
0
Saúde
42%
Último commit
há 2 dias
Versão
—
Issues abertas
4
Contribuidores
1

Casos de uso

  • Automação de respostas e gerenciamento de conversas WhatsApp via Claude
  • Busca semântica em histórico de mensagens com pgvector
  • Transcrição automática de áudios e notas de voz com Whisper
  • Monitoramento e reação em grupos via MCP

Veredito

Integração sofisticada e bem arquitetada para WhatsApp, com suporte a busca semântica e múltiplas contas. Exige infraestrutura (Docker/PostgreSQL) e conhecimento técnico, mas oferece controle total sobre comunicações WhatsApp via MCP.

README

A tradução para o português deste README ainda está na fila.

WhatsApp Bridge

Production-grade WhatsApp MCP server built with Go (whatsmeow) + Python (FastMCP).

Connect Claude Code (or any MCP-compatible AI) to WhatsApp - send messages, react, edit, delete, monitor groups, search by meaning, download media, transcribe voice notes, and more.

Architecture

Claude Code <-stdio-> Python MCP Server <-HTTP-> Go Bridge <-WebSocket-> WhatsApp
                           |                        |
                     semantic_search           PostgreSQL / SQLite
                           |                        |
                     pgvector (in PG)       Python Dashboard (read-only)
                                            (FastAPI + HTMX)

Components:

  • Go Bridge - WhatsApp protocol via whatsmeow, REST API, rate limiting, auto media download, link indexing, voice note transcription, telemetry
  • Python MCP Server - 17 MCP tools over stdio, multi-account support
  • Python Dashboard - Optional read-only web UI (FastAPI + HTMX)
  • Python Embedder - Background worker that embeds messages into pgvector for semantic search
  • Python Transcriber - Background worker that transcribes voice notes via Whisper with retry
  • PostgreSQL + pgvector - Primary database with built-in vector search
  • SQLite - Lightweight alternative for single-process setups (no vector search)

Quick Start

Option A: Docker (recommended)

git clone https://github.com/asimzeeshan/WhatsApp-bridge.git
cd WhatsApp-bridge
cp .env.example .env
cp config.example.toml config.toml
# Edit .env: set your POSTGRES_PASSWORD
# Edit config.toml: set bridge.database.driver = "postgres"

# Start core stack
docker compose up -d

# First-time QR scan
docker compose logs -f bridge
# Scan the QR code with WhatsApp > Settings > Linked Devices > Link a Device

# Optional: dashboard and whisper transcription
docker compose --profile dashboard --profile whisper up -d

Services started:

  • Bridge: http://127.0.0.1:8080
  • PostgreSQL + pgvector: 127.0.0.1:5432
  • Embedder: background worker (auto-embeds new messages)
  • Transcriber: background worker (auto-transcribes voice notes)
  • Dashboard (optional): http://127.0.0.1:9090

Option B: Native (macOS/Linux)

Prerequisites: Go 1.25+, Python 3.11+, uv

git clone https://github.com/asimzeeshan/WhatsApp-bridge.git
cd WhatsApp-bridge
cp config.example.toml config.toml

First run (QR scan):

make build-bridge
make run-bridge       # scan QR code, then Ctrl+C

Run everything:

make run-all          # bridge + dashboard in background
make status           # check running status
make stop-all         # stop everything

If your session expires (~20 days), run make run-bridge in the foreground to scan a new QR code.

Connect Claude Code

Add to your .mcp.json:

{
  "mcpServers": {
    "whatsapp-mcp": {
      "type": "stdio",
      "command": "uv",
      "args": ["run", "--directory", "/path/to/WhatsApp-bridge/mcp-server", "whatsapp-mcp"],
      "env": {
        "BRIDGE_URL": "http://127.0.0.1:8080"
      }
    }
  }
}

Multi-account setup (optional)

Run multiple bridge instances for different WhatsApp accounts:

./bin/whatsapp-bridge --config config.primary.toml    # port 8080
./bin/whatsapp-bridge --config config.secondary.toml  # port 8081 (read-only monitoring)

Use BRIDGE_ACCOUNTS instead of BRIDGE_URL:

{
  "env": {
    "BRIDGE_ACCOUNTS": "[{\"name\":\"primary\",\"url\":\"http://127.0.0.1:8080\"},{\"name\":\"secondary\",\"url\":\"http://127.0.0.1:8081\",\"read_only\":true}]"
  }
}

All MCP tools accept an optional account parameter. Send operations are blocked on read-only accounts.

MCP Tools (17)

ToolDescription
send_messageSend text to individual contact
send_group_messageSend text to group
send_reactionReact to a message with an emoji
edit_messageEdit a previously sent message
revoke_messageDelete/revoke a message for everyone
check_new_messagesPoll for new messages in a single chat (server-side watermarks)
check_triggersBatch check multiple chats at once (single call, per-JID watermarks, dry_run support)
get_messagesRetrieve message history
get_unread_chatsList chats with unread messages
get_unread_messagesFlat list of all unread messages
list_contactsList all contacts
get_contactGet contact details
list_groupsList all groups
get_groupGet group metadata + participants
send_mediaSend image/video/audio/document
download_mediaDownload media from received messages
semantic_searchSearch messages by meaning (pgvector similarity)

Features

Messaging

  • Text, media, voice notes - Send and receive all message types
  • Emoji reactions - Send and receive reactions on messages
  • Message editing - Edit sent messages (within WhatsApp's 20-minute window)
  • Message revocation - Delete messages for everyone
  • Quoting and mentions - Reply to messages and @mention participants

Media

  • Auto image download - All received images saved to media/images/YYYY-MM-DD/
  • Auto audio download - All received voice notes saved to media/audio/YYYY-MM-DD/
  • Media download API - Download any media on demand via download_media tool or REST API
  • MIME type handling - Correct file extensions even for parameterized types (e.g. audio/ogg; codecs=opus)
  • Local path tracking - Downloaded media paths stored in database for transcription pipeline

Storage

  • PostgreSQL + pgvector - Production database with concurrent access and built-in vector search (recommended)
  • SQLite - Lightweight alternative with WAL mode (single-process, no vector search)
  • Config-driven: switch between SQLite and PostgreSQL via config.toml

Intelligence

  • Semantic search - Find messages by meaning using pgvector cosine similarity
  • Multilingual embeddings - paraphrase-multilingual-MiniLM-L12-v2 model (384 dimensions, 50+ languages)
  • Voice note transcription - Automatic via Whisper with WAV conversion (supports whisper.cpp and OpenAI-compatible APIs)
  • Transcription retry - Background worker with exponential backoff, re-download on missing files
  • Link indexing - URLs extracted and categorized (YouTube, GitHub, Twitter/X, etc.)

Operations

  • Multi-account - Multiple WhatsApp accounts with read-only support
  • Rate limiting - Configurable token bucket with jitter to prevent bans
  • Telemetry - Daily message/media counters, per-tool-call tracking
  • Health endpoint - Memory, disk, DB sizes, goroutine count
  • Dashboard - Dark-themed HTMX UI with auto-refreshing status
  • Docker deployment - Full stack with Compose, health checks, service dependencies
  • macOS launchd - Auto-start on login, auto-restart on crash

REST API

EndpointMethodDescription
/api/statusGETConnection state and identity
/api/healthGETResource usage (memory, disk, DB sizes)
/api/check?jid={jid}GETNew messages since last watermark (single JID)
/api/check/triggersPOSTBatch check multiple JIDs at once (dry_run support)
/api/sendPOSTSend text message
/api/send/mediaPOSTSend media message
/api/send/reactionPOSTSend emoji reaction
/api/send/editPOSTEdit a sent message
/api/send/revokePOSTRevoke/delete a message
/api/messagesGETMessage history
/api/contactsGETAll contacts
/api/groupsGETAll groups
/api/linksGETIndexed links
/api/telemetry/dailyGETDaily stats
/api/downloadPOSTDownload media from a message

Configuration

Credentials live in .env (copy from .env.example). Bridge settings in config.toml (copy from config.example.toml).

[bridge]
addr = "127.0.0.1:8080"

[bridge.database]
driver = "postgres"  # or "sqlite"
# DSN set in .env as PG_DSN

[bridge.ratelimit]
messages_per_second = 0.5

[bridge.media]
auto_download_images = true
auto_download_audio = true
images_dir = "./media/images"
audio_dir = "./media/audio"

[bridge.transcription]
enabled = true
whisper_url = "http://127.0.0.1:8443/inference"
model = "large-v3"
language = ""  # empty = auto-detect

Docker Services

ServiceImagePortDescription
bridgeBuilt from bridge/Dockerfile8080Go WhatsApp bridge
mcp-serverBuilt from mcp-server/Dockerfile-MCP tools (stdio)
postgrespgvector/pgvector:pg175432Database + vector search
embedderBuilt from embedder/Dockerfile-Background embedding worker
transcriberBuilt from transcriber/Dockerfile-Background transcription worker
dashboardBuilt from dashboard/Dockerfile9090Web UI (optional, --profile dashboard)
whisperspeaches-ai/speaches8443Voice transcription (optional, --profile whisper)

Voice Note Transcription

The bridge supports automatic voice note transcription through two methods:

In-bridge transcription

The Go bridge can transcribe voice notes inline as they arrive. Configure in config.toml:

[bridge.transcription]
enabled = true
whisper_url = "http://127.0.0.1:8443/inference"

Standalone transcription worker

For more robust handling with retry logic, run the Python transcriber worker:

cd transcriber
uv run whatsapp-transcriber --pg "$PG_DSN" --whisper "$WHISPER_URL"

The worker:

  • Polls PostgreSQL for untranscribed audio messages
  • Converts ogg/opus to WAV using opusdec (preferred) or afconvert (macOS fallback)
  • Sends WAV to whisper.cpp /inference endpoint
  • Retries with exponential backoff when Whisper is unavailable
  • Re-downloads audio via bridge API if local file is missing

Whisper backends

  • whisper.cpp (native) - Use /inference endpoint, requires WAV input and temperature=0.0
  • speaches-ai (Docker) - OpenAI-compatible API at /v1/audio/transcriptions
  • Any OpenAI-compatible Whisper API

Ban Risk Assessment

This project uses whatsmeow, a reverse-engineered WhatsApp Web client. Using unofficial APIs carries inherent risk.

Built-in Protections

ProtectionImplementation
Rate limitingToken bucket (0.5 msg/sec default) with random jitter
Cooldown markerBan detected -> data/cooldown file, 10 min pause
Exponential backoffReconnection: 1s -> 60s cap, with jitter
Permanent disconnectTemporaryBan, LoggedOut, ClientOutdated all stop the bridge
No bulk endpointsSingle-message sends only

Recommendations

  • Use a secondary phone number, not your primary
  • Keep whatsmeow updated (go get -u go.mau.fi/whatsmeow@latest)
  • Keep message volume reasonable (< 200 messages/day for automated sends)

Security

  • HTTP API bound to 127.0.0.1 only (bridge and dashboard)
  • All SQL queries use parameterized statements
  • Path traversal protection on download directories
  • Rate limiter enforced via chi middleware
  • Dashboard is read-only
  • Docker containers run as non-root (UID 1000)

Makefile Targets

TargetDescription
make buildBuild bridge + install MCP + install dashboard
make build-bridgeCompile Go bridge binary
make run-allBuild and start bridge + dashboard in background
make stop-allStop all services
make statusShow running status
make run-bridgeStart bridge foreground (for QR scan)
make logs-bridgeTail bridge logs
make logs-dashboardTail dashboard logs
make testRun Go tests
make lintRun Go vet
make service-installInstall macOS launchd service
make service-restartRestart macOS launchd service
make service-statusCheck macOS launchd service status
make cleanRemove binaries and database files

Project Structure

WhatsApp-bridge/
  bridge/            # Go bridge (whatsmeow + REST API)
    api/             #   HTTP handlers (send, download, status, health)
    client/          #   WhatsApp client wrapper (events, media download)
    config/          #   Configuration parsing
    media/           #   OGG analysis, Whisper transcription
    store/           #   Database layer (PostgreSQL + SQLite, migrations)
  mcp-server/        # Python MCP server (FastMCP, 16 tools)
  dashboard/         # Python dashboard (FastAPI + HTMX)
  embedder/          # Python embedding worker (sentence-transformers + pgvector)
  transcriber/       # Python transcription worker (Whisper + retry logic)
  scripts/           # Service install, migration scripts
  docs/              # Testing guide
  data/              # Runtime: DB, PID files (gitignored)
  logs/              # Runtime logs (gitignored)
  media/             # Downloaded images + audio (gitignored)
  docker-compose.yml # Full stack Docker deployment
  config.toml        # Runtime config (gitignored)
  Makefile           # Native build and run targets

CI/CD

A GitHub Actions workflow runs daily at 3 AM UTC to update Go and Python dependencies, build, test, and open a PR if anything changed.

Testing

See docs/TESTING.md for build validation, security audit results, integration test checklist, and known limitations.

Disclaimer

This project uses unofficial WhatsApp APIs through whatsmeow. It is not endorsed by, affiliated with, or supported by WhatsApp or Meta. Use at your own risk. Using unofficial APIs may violate WhatsApp's Terms of Service and could result in account restrictions.

Author

Asim Zeeshan

License

MIT

Ver o original no GitHub

Bom para

Relacionados