whatsapp-notify-mcp

Send agent status to your WhatsApp from Cursor, Claude Code, or Codex.

Agents call MCP tools (task_completed, task_failed, task_progress, …). This package talks to the Meta WhatsApp Cloud API directly — no clone of a backend repo required.

Quick add (after you have Meta credentials)

Cursor / Claude Code — .mcp.json or Cursor MCP settings

{
  "mcpServers": {
    "whatsapp-bridge": {
      "command": "npx",
      "args": ["-y", "whatsapp-notify-mcp"],
      "env": {
        "WHATSAPP_TOKEN": "EAA...",
        "WHATSAPP_PHONE_NUMBER_ID": "1234567890",
        "ALLOWED_WHATSAPP_NUMBER": "91XXXXXXXXXX"
      }
    }
  }
}

Codex — ~/.codex/config.toml or project .codex/config.toml

[mcp_servers.whatsapp-bridge]
command = "npx"
args = ["-y", "whatsapp-notify-mcp"]

[mcp_servers.whatsapp-bridge.env]
WHATSAPP_TOKEN = "EAA..."
WHATSAPP_PHONE_NUMBER_ID = "1234567890"
ALLOWED_WHATSAPP_NUMBER = "91XXXXXXXXXX"

Or: codex mcp add whatsapp-bridge --env WHATSAPP_TOKEN=... -- npx -y whatsapp-notify-mcp

Setup from scratch (Meta WhatsApp)

You need a free Meta developer app and a WhatsApp test (or production) number.

1. Create a Meta app

1. Go to Meta for Developers and sign in.
2. My Apps → Create App.
3. Pick a use case that includes WhatsApp (or add the WhatsApp product after create).
4. Open the app → add WhatsApp if it is not already added.

2. Get your credentials (API Setup / Try it out)

In the WhatsApp product:

1. Note the Phone number ID (digits) → WHATSAPP_PHONE_NUMBER_ID.
2. Note the WhatsApp Business Account ID (optional for notify-only).
3. Click Generate token (or use Graph API Explorer) and copy the access token → WHATSAPP_TOKEN.
   Temporary tokens expire; for daily use create a System User permanent token with whatsapp_business_messaging.
4. Under To / recipients, add your personal WhatsApp number and verify the code Meta sends.

3. Set your phone as the notify destination

ALLOWED_WHATSAPP_NUMBER = your number in digits only, country code included, no +.

Examples:

• India: 9198XXXXXXXX
• US: 15551234567

4. (Test number) Register & allowlist

If you use Meta’s test number:

1. Register the number if the API asks (/register with a PIN — Meta’s UI often does this).
2. Only numbers you added as test recipients can receive messages.
3. Publish the app when Meta blocks real chat webhooks; for outbound notify-only (this MCP), sending to an allowlisted recipient usually works once the token and phone ID are valid.

5. Paste into your agent MCP config

Use the Cursor / Claude / Codex snippets above. Reload MCP / restart the client.

6. Smoke test

Ask the agent:

Call send_message on whatsapp-bridge with text “MCP is live”

You should get that WhatsApp message within a few seconds.

Tools

| Tool | When to call | |------|----------------| | task_started | Beginning a discrete task | | task_progress | Milestones (message, optional percentage) | | task_completed | Required on success (summary, optional changed_files) | | task_failed | Required on error / blocked | | send_message | Freeform note or question |

task_id is optional for normal IDE chats.

Environment variables

| Variable | Required | Purpose | |----------|----------|---------| | WHATSAPP_TOKEN | Yes* | Meta access token | | WHATSAPP_PHONE_NUMBER_ID | Yes* | Sending phone number ID | | ALLOWED_WHATSAPP_NUMBER | Yes* | Your WhatsApp (digits only) |

*Or, for the full whatsapp-to-cursor monorepo bridge only:

| Variable | Purpose | |----------|---------| | BACKEND_URL | e.g. http://127.0.0.1:8787 | | BRIDGE_TOKEN | Shared secret for /api/notify |

If WhatsApp env is set, direct Meta send wins. Otherwise the MCP posts to the bridge backend.

Requirements

• Node.js 20+ (npx will fetch this package)
• A Meta WhatsApp Cloud API app + token
• Your phone added as a recipient (test) or reachable in production

License

MIT