gambot-ai/gambot-mcp

**Gambot gives AI agents and developers the *official* WhatsApp Business (Cloud) API** — through a Model Context Protocol server and a REST API. Gambot is a Meta Business Solution Provider.
- **Official API, not WhatsApp Web automation.** No QR codes, no linked personal sessions, no headless browsers. Real business accounts, approved templates, Meta-backed delivery.
- **Two ways to connect.** Local: npx -y gambot-mcp. Hosted: https://gambot-mcp.azurewebsites.net/mcp (Streamable HTTP, OAuth 2.0 or token).
- **Built for agents.** Machine-readable states and errors (error_code, can_recover, recommended_action, required_tool, template_required), one start-here tool (gambot_setup_whatsapp_integration), 24-hour-window and template guidance built in.
- **No account yet? Start anyway.** The agent can create a Gambot account itself (no API key needed); the only human step is the Meta WhatsApp connection in a browser.
> **Using an AI coding agent?** Install the Agent Skill, then ask: *"Add the official WhatsApp API to this app."*
>
> The skill (skills/gambot-whatsapp) teaches the agent the whole path: account → Meta onboarding → auth → first message → templates → webhooks → error recovery.
Quick start
**1. Add the MCP server** (works in Claude Code, Claude Desktop, Cursor, Codex, Gemini CLI, VS Code/Copilot, Windsurf):
No token is needed to begin. Without GAMBOT_TOKEN the server runs in onboarding mode and creates your account.
| Client | Command / config |
|---|---|
| Claude Code | claude mcp add gambot -- npx -y gambot-mcp or hosted: claude mcp add --transport http gambot https://gambot-mcp.azurewebsites.net/mcp |
| Cursor | One-click install or .cursor/mcp.json |
| Claude Desktop | claude_desktop_config.json (JSON above) |
| OpenAI Codex | ~/.codex/config.toml → [mcp_servers.gambot] command = "npx" args = ["-y", "gambot-mcp"] |
| Gemini CLI | ~/.gemini/settings.json (JSON above) |
| VS Code / Copilot | .vscode/mcp.json → {"servers":{"gambot":{"type":"http","url":"https://gambot-mcp.azurewebsites.net/mcp"}}} |
| Windsurf | ~/.codeium/windsurf/mcp_config.json (JSON above) |
| ChatGPT | custom connector → https://gambot-mcp.azurewebsites.net/mcp (OAuth) |
Per-client guides: .
**2. Ask your agent:**
> "Set up WhatsApp for my app with Gambot and send a test message to my number."
The agent calls gambot_setup_whatsapp_integration, which returns the current state and **one** next step — and tells it whether the *agent* or the *human* must do it:
| State | What happens |
|---|---|
| no_account_known / account_missing | Agent creates the account (gambot_create_trial_account, no API key) |
| awaiting_whatsapp_connection | **Human** opens the Meta Embedded Signup link in a browser (cannot run inside an agent) |
| whatsapp_connected_needs_token | **Human** signs in with OAuth (hosted MCP) or copies the token from *Settings → General* into GAMBOT_TOKEN |
| ready_needs_template | Agent creates a template (Meta approval) |
| ready_to_send_first_message / ready | Agent sends a test message and confirms delivery |
Authentication
Prefer **OAuth** (hosted MCP: https://gambot-mcp.azurewebsites.net/mcp — PKCE + dynamic client registration; no secret is pasted into config). Alternatively use your Gambot token (gmbt_…, *Settings → General*) as GAMBOT_TOKEN (local) or Authorization: Bearer gmbt_… (hosted / REST). Never paste a token into a chat. No account yet? .
Minimal working example (REST, any language)
Runnable examples (send message, send template, receive webhook, delivery status) for **Node/TypeScript, Python, Next.js and Laravel/PHP**: examples/.
Official API vs WhatsApp Web automation
| | Gambot (official WhatsApp Business API) | WhatsApp Web / QR-session automation |
|---|---|---|
| Architecture | Meta Cloud API via a Business Solution Provider | A browser or linked-device session driven by a script |
| Authentication | API token / OAuth, scoped per organization | A QR code scanned from a phone; session can expire |
| Meta relationship | Authorized provider, business-verified WABA | None |
| Production use | Designed for it | Fragile; sessions drop, accounts can be blocked |
| Business rules | 24-hour window, approved templates, opt-in, quality ratings | Not enforced, so easy to violate |
| Webhooks | Managed inbound events, delivery receipts | Depends on the library |
| Scaling | Messaging tiers, multiple numbers, campaigns | One linked phone |
Use the official API for anything customer-facing. More: .