WhatsApp

Connect a WhatsApp Business number to your Claude Code session via an MCP server.

The MCP server receives WhatsApp messages through Meta's Cloud API webhook, forwards them to your Claude Code session, and provides tools to reply and react. When someone messages your WhatsApp Business number, the server delivers the message to the assistant.

Prerequisites

• Bun — the MCP server runs on Bun. Install with curl -fsSL https://bun.sh/install | bash.
• A Meta Business Account with a Meta App that has the WhatsApp product added.
• A publicly reachable HTTPS endpoint for the webhook (use ngrok for development).

Quick Setup

Default pairing flow for a single-user DM setup. WhatsApp Cloud API is 1:1 only — no group chat support.

1. Create a Meta App with WhatsApp.

1. Go to the Meta App Dashboard and create a new app.
2. Select the "Other" use case, then choose "Business" app type.
3. Once created, find "Connect with customers through WhatsApp" in Use Cases and set it up.
4. Connect your Meta Business Portfolio (create one at business.facebook.com if needed).
5. In the WhatsApp API Setup page, note your Phone Number ID — you'll need it in step 3.

2. Generate a permanent access token.

The API Setup page gives you a temporary 24-hour token for testing. For production:

1. Go to Business Settings > System Users and create a System User (Admin role).
2. Add your Meta App as an asset with full control.
3. Click Generate New Token, select your app, and grant the whatsapp_business_messaging permission.
4. Copy the token — this is your WHATSAPP_ACCESS_TOKEN. It does not expire unless manually revoked.

3. Configure credentials.

These are Claude Code commands — run claude to start a session first.

Using the configure skill:

/whatsapp:configure token EAABwzX... phone 123456789012345 verify my-secret-token

Or create ~/.claude/channels/whatsapp/.env manually:

WHATSAPP_ACCESS_TOKEN=EAABwzX...your-token-here
WHATSAPP_PHONE_NUMBER_ID=123456789012345
WHATSAPP_VERIFY_TOKEN=my-secret-verify-token-123
WHATSAPP_APP_SECRET=abc123...your-app-secret
WHATSAPP_WEBHOOK_PORT=3000

4. Set up the webhook.

The server needs to receive HTTPS webhook callbacks from Meta. For development, use ngrok:

ngrok http 3000

Then register the webhook in the Meta App Dashboard:

1. Go to WhatsApp > Configuration > Webhook.
2. Set Callback URL to https://<your-ngrok-url>/webhook.
3. Set Verify token to the same string from WHATSAPP_VERIFY_TOKEN.
4. Click Verify and Save.
5. Subscribe to the messages webhook field.

Note: ngrok URLs change on every restart. You'll need to update the webhook URL in Meta each time. For a persistent setup, use a real domain with HTTPS or Cloudflare Tunnel.

5. Launch with the channel flag.

Exit your session and start a new one:

claude --dangerously-load-development-channels server:whatsapp

6. Pair.

With Claude Code running, message your WhatsApp Business number — it replies with a 6-character pairing code. In your Claude Code session:

/whatsapp:access pair <code>

Your next message reaches the assistant.

7. Lock it down.

Pairing is for capturing phone numbers. Once you're in, switch to allowlist so strangers don't get pairing-code replies:

/whatsapp:access policy allowlist

Access Control

The /whatsapp:access skill manages who can reach you:

Quick reference: sender IDs are phone numbers without the + prefix (e.g. 15559876543). Default policy is pairing. All state lives in ~/.claude/channels/whatsapp/access.json.

The /whatsapp:configure skill manages credentials, shows setup status, and guides you through the lockdown flow.

Tools Exposed to the Assistant

There is no edit_message tool — WhatsApp Cloud API does not support editing sent messages. If the assistant needs to correct something, it sends a new message.

Media

Inbound: Photos, documents, audio, and video are downloaded to ~/.claude/channels/whatsapp/inbox/ on arrival. The local path is included in the <channel> notification as image_path so the assistant can Read it. WhatsApp compresses photos.

Outbound: The reply tool accepts file paths via the files parameter. Files are uploaded to the WhatsApp media API and sent as image or document messages.

No History or Search

WhatsApp's Cloud API exposes neither message history nor search. The bot only sees messages as they arrive. If the assistant needs earlier context, it will ask you to paste or summarize.

Architecture

This channel differs from Telegram in one key way: webhooks instead of long polling. Telegram's grammy library polls for new messages; WhatsApp's Cloud API pushes messages to your HTTPS endpoint via Meta's webhook system.

The server runs a local HTTP server (Bun.serve()) that handles:

• GET /webhook — Meta's verification handshake
• POST /webhook — incoming messages, validated with X-Hub-Signature-256 when APP_SECRET is configured
• GET /health — health check endpoint

No external dependencies beyond @modelcontextprotocol/sdk — all WhatsApp API calls use native fetch.

Limitations

• No message editing — WhatsApp Cloud API does not support editing sent messages.
• No group chats — WhatsApp Cloud API bots operate 1:1 only.
• Webhook requires HTTPS — Meta only delivers webhooks to HTTPS endpoints. Use ngrok or a reverse proxy for development.
• No message history — the bot only sees messages as they arrive.
• Temporary test tokens expire in 24 hours — use a System User token for production.
• ngrok URL changes on restart — requires re-registering the webhook in Meta each time.

License

Apache-2.0