Community source release (MIT). Self-host using your own credentials. No NabuxAI production accounts or hosted-service access are included.

WhatsApp MCP by Nabux

Multi-user, multi-number WhatsApp MCP Gateway powered by Meta's official WhatsApp Cloud API.

Official API, Nabux gateway: WhatsApp messaging and webhook operations use Meta's supported WhatsApp Business Platform / Cloud API. The MCP server itself is built and operated by Nabux; it is not a Meta-authored MCP server.

Production target: https://wa.nabuxai.com
MCP endpoint: https://wa.nabuxai.com/mcp
Webhook callback: https://wa.nabuxai.com/webhook

What this gateway does

• Onboards WhatsApp Business accounts through Meta Embedded Signup.

• Supports multiple users and multiple WhatsApp Business phone numbers.

• Keeps Meta access tokens encrypted at rest on the Nabux server.

• Exposes OAuth 2.1 + PKCE for ChatGPT, Claude, Cursor and other MCP clients.

• Receives Meta WhatsApp webhooks, verifies X-Hub-Signature-256, and stores messages/status events.

• Lets an authenticated MCP client search only its own webhook-backed inbox/history.

• Sends text, templates and media through the official Cloud API.

• Enforces a local 24-hour check before free-form text/media sends; use approved templates to start/reopen opted-in conversations.

• Exposes an opaque Account Key for trusted Nabux server-to-server integrations.

It does not use WhatsApp Web scraping, browser automation, cookies, QR-linked-device reverse engineering, private APIs or user passwords.

Related MCP server: WhatsApp Business API MCP Server

Architecture

Customer browser
  -> wa.nabuxai.com/connect
  -> Meta Embedded Signup
  -> WhatsApp Business Account / phone number
  -> encrypted token vault (SQLite /data)

WhatsApp customer
  -> Meta WhatsApp Cloud API
  -> POST https://wa.nabuxai.com/webhook
  -> signature verification
  -> contacts + messages + statuses DB

ChatGPT / Claude / Cursor
  -> OAuth 2.1 + PKCE
  -> https://wa.nabuxai.com/mcp
  -> owner-isolated MCP tools

Trusted Nabux backend
  -> INTERNAL_SERVICE_TOKEN
  -> /internal/v1/...

MCP tools

Accounts / metadata

• whatsapp_accounts

• whatsapp_profile

• whatsapp_list_templates

• whatsapp_register_phone

Webhook-backed data

• whatsapp_list_contacts

• whatsapp_list_conversations

• whatsapp_get_conversation

• whatsapp_search_messages

• whatsapp_recent_messages

• whatsapp_media_metadata

Messaging

• whatsapp_send_text

• whatsapp_send_template

• whatsapp_send_media

• whatsapp_mark_read

whatsapp_send_text and whatsapp_send_media require the gateway to have observed an inbound message from that contact in the previous 24 hours. To initiate/reopen a conversation, use an approved template and only message recipients who have provided the required opt-in.

Data collection model

This gateway collects data delivered to your WhatsApp Business phone number through official Meta webhooks. It can therefore search and analyze messages received after the webhook is active, plus outbound messages sent through this gateway.

It is intentionally not a WhatsApp personal-history scraper. It cannot pull arbitrary old personal chats/groups from WhatsApp Web. If a separate personal collector is ever added, keep it isolated from this official Business gateway and clearly label it unofficial.

Required Meta setup

Create/configure a Meta app with WhatsApp Business Platform and Embedded Signup.

Required production capabilities depend on your Meta app/business setup. For a multi-customer Embedded Signup release, Meta's current official guidance requires App Review/Advanced Access for the relevant WhatsApp/Business permissions. Meta's Embedded Signup flow returns the WABA/phone information, and this gateway subscribes the selected WABA to the app's webhook after connection.

Configure the webhook callback:

https://wa.nabuxai.com/webhook

Use the same secret value in Meta's webhook Verify Token field and the server variable:

WA_VERIFY_TOKEN=<random-secret>

Subscribe the WhatsApp Business Account webhook fields needed for messages. The gateway accepts message and delivery/read/status events and verifies Meta's request signature before ingestion.

Environment variables

Copy .env.example and set secrets in Coolify rather than committing them.

APP_NAME="WhatsApp MCP by Nabux"
PUBLIC_BASE_URL=https://wa.nabuxai.com
APP_SECRET_KEY=<random-32+-char-secret>

WA_APP_ID=<meta-app-id>
WA_APP_SECRET=<meta-app-secret>
WA_EMBEDDED_CONFIG_ID=<embedded-signup-configuration-id>
WA_GRAPH_VERSION=v26.0
WA_GRAPH_BASE=https://graph.facebook.com
WA_VERIFY_TOKEN=<random-webhook-verify-token>
WA_WEBHOOK_PATH=/webhook

INTERNAL_SERVICE_TOKEN=<random-server-to-server-secret>

Generate secrets locally/server-side, for example:

python -c "import secrets; print(secrets.token_urlsafe(48))"

Never commit WA_APP_SECRET, Meta access tokens, APP_SECRET_KEY, or INTERNAL_SERVICE_TOKEN.

Coolify deployment

Deploy this branch as a separate service:

Repository: NabuxAi/TelegramMCP
Branch: feature/whatsapp-mcp-gateway
Compose file: docker-compose.coolify.yml
Domain: wa.nabuxai.com
Container port: 8000

Set all environment variables in Coolify and attach persistent storage to /data (the provided compose file creates whatsapp-mcp-data).

After deployment:

1. Open https://wa.nabuxai.com/.

2. Click Connect WhatsApp.

3. Complete Meta Embedded Signup.

4. Confirm the dashboard shows the phone number and wa_... Account Key.

5. In Meta Webhooks, verify https://wa.nabuxai.com/webhook using WA_VERIFY_TOKEN.

6. Send a WhatsApp message to the connected Business number.

7. Connect an MCP client to https://wa.nabuxai.com/mcp.

8. Call whatsapp_list_conversations and whatsapp_get_conversation.

9. Reply with whatsapp_send_text while the 24-hour customer-service window is open.

10. Test an approved template with whatsapp_send_template.

Embedded Signup notes

The /connect page uses Meta's Facebook JavaScript SDK and an Embedded Signup configuration ID. It listens for the WA_EMBEDDED_SIGNUP completion event and combines the returned WABA/phone information with the exchangeable authorization code. The server then:

1. exchanges the code for an access token;

2. verifies access to the selected WABA;

3. subscribes the app to the WABA;

4. discovers its phone numbers;

5. stores the token encrypted for each connected phone number.

A newly onboarded phone number may still need Cloud API registration/two-step verification according to its state. The MCP tool whatsapp_register_phone(pin) performs the official registration call with a six-digit PIN.

Security model

• Meta access tokens: Fernet-encrypted using a key derived from APP_SECRET_KEY.

• MCP bearer/refresh tokens: SHA-256 hashes only in the database.

• Browser session: signed HttpOnly/Secure cookie.

• Embedded Signup completion: short-lived same-site connect-state cookie.

• Webhooks: X-Hub-Signature-256 HMAC verification using the Meta app secret.

• MCP data access: every account lookup is constrained to the authenticated local owner.

• Internal API: separate INTERNAL_SERVICE_TOKEN.

• No Meta token is returned to ChatGPT/Claude/Cursor.

Official API vs. ban risk

Using WhatsApp Cloud API removes the risk associated with reverse-engineered WhatsApp Web/private-protocol automation, but it does not guarantee that an account can never be restricted. Businesses still need to follow Meta/WhatsApp messaging, opt-in, template, commerce and quality policies.

Current scope / next additions

Useful next modules after first production E2E:

• webhook media download + encrypted/object-storage archive;

• semantic/vector search over stored conversations;

• template creation/management tools;

• conversation labels/CRM notes;

• NabuGen WhatsApp destination adapter;

• optional Coexistence-specific Embedded Signup configuration;

• retention controls and per-owner data deletion.