Gambot MCP Server — WhatsApp API for AI agents

Connect WhatsApp to Claude, ChatGPT, Gemini and Cursor. This is a Model Context Protocol server for the Gambot WhatsApp Business API (an official, Meta‑approved WhatsApp Business Solution Provider). It lets any MCP‑compatible client drive your Gambot account through tools — send WhatsApp messages & templates, run marketing campaigns, and manage contacts, leads, cases, tasks, quotes, invoices, orders, forms, signatures, document templates and users.

One-click install (Cursor): ➕ Add to Cursor — then paste your Gambot token into the server's env.

No Gambot account yet? Install exactly the same way but leave the token empty — the server starts in token‑less onboarding mode and the agent creates your WhatsApp Business account from scratch. See Token‑less onboarding mode.

It wraps the public REST API at https://api.gambot.co.il/api/v1, authenticated with your organization's Gambot Token. MCP is an AI‑facing interface over Gambot — it uses the same business logic as the REST API, and is not a separate backend.

Why Gambot instead of building on Meta's Cloud API directly

Both Gambot and a do-it-yourself integration run on the same official WhatsApp Business (Cloud) API from Meta — Gambot is an authorized Meta Business Solution Provider (BSP), not a WhatsApp Web/unofficial workaround, and you keep your own number/WABA. The difference is how much infrastructure you build and maintain:

Net: same official API, none of the plumbing to build or maintain, compliance enforced for you, and it's agent-ready. Full comparison: https://gambot.co.il/whatsapp-api-vs-meta-cloud-api/.

Supported AI clients

Step‑by‑step setup guides per client:

• Cursor — one‑click install or .cursor/mcp.json → https://gambot.co.il/whatsapp-mcp/cursor/
• Claude — Claude Desktop (npx) or a remote connector → https://gambot.co.il/whatsapp-mcp/claude/
• ChatGPT — hosted connector (Streamable HTTP + OAuth) → https://gambot.co.il/whatsapp-mcp/chatgpt/
• Gemini — Gemini CLI settings → https://gambot.co.il/whatsapp-mcp/gemini/

Hosted (remote) server: https://gambot-mcp.azurewebsites.net/mcp (Streamable HTTP; OAuth or bearer token) — no local install needed.

Prerequisites

• Node.js 18+
• No account yet? You need nothing — start the server without a token and it runs in token‑less onboarding mode to create your Gambot account from scratch.
• Already have an account? A Gambot Token (gmbt_…) from the Gambot admin panel → Settings → General, to unlock the full tool set.

Quick start (npx — recommended)

Once published to npm, no clone or build is needed — MCP clients run it on demand with npx.

Cursor (.cursor/mcp.json) / Claude Desktop (claude_desktop_config.json)

{
  "mcpServers": {
    "gambot": {
      "command": "npx",
      "args": ["-y", "gambot-mcp"],
      "env": {
        "GAMBOT_TOKEN": "gmbt_your_token_here"
      }
    }
  }
}

Optional env var GAMBOT_API_BASE overrides the base URL (defaults to https://api.gambot.co.il/api/v1).

No token yet? Token‑less onboarding mode

You don't need a Gambot account to get started. The token is a result of finishing onboarding (chicken‑and‑egg: a brand‑new org has no token yet), so the server also runs without GAMBOT_TOKEN. Just omit it — leave env empty:

{
  "mcpServers": {
    "gambot": {
      "command": "npx",
      "args": ["-y", "gambot-mcp"]
    }
  }
}

Started token‑less, it enters onboarding mode and exposes only the public self‑serve tools — create a brand‑new account (free / co‑existence / bring‑your‑own number, or buy a number after e‑mail+WhatsApp verification), open the Meta Embedded Signup link in the browser, then poll gambot_get_onboarding_status until WhatsApp is connected. Just tell the agent "create a Gambot WhatsApp account for my business" and it walks you through it. Once connected, you get your gmbt_… token in‑app (Settings → General); add GAMBOT_TOKEN to the env above to unlock the full tool set. (Remote/OAuth clients like Claude & ChatGPT authorize per‑session through the hosted consent page instead.)

Local development (from source)

npm install
npm run build

Then point your MCP client at the built entrypoint:

{
  "mcpServers": {
    "gambot": {
      "command": "node",
      "args": ["C:/Users/you/source/repos/gambot/gmbt_mcp/dist/index.js"],
      "env": {
        "GAMBOT_TOKEN": "gmbt_your_token_here"
      }
    }
  }
}

Tools

Bots & automations model

A conversational bot in Gambot is usually a package of botomations that were deployed together and share a sourceFlowId. gambot_list_bots returns role, triggerKind, sourceFlowId and linkedBotomationId on every item so an agent can reconstruct it. The full package, in order, is:

1. Main bot (role: main_bot, isBot: true) — the conversation itself. Three flavours:
   • menu — an opening template whose quick-reply buttons route to replies.
   • ai — a GambotAi step that hands the conversation to Gambot AI (the AI operator).
   • combined — a menu where some branches route to Gambot AI.
2. Activator / מפעיל (role: activator) — the trigger that starts the bot. triggerKind tells you how it fires: incoming_message (keyword/any), template_button, campaign_lead (a lead arrived from an ad/campaign), owner_assigned (a contact was assigned to an owner — e.g. Gambot AI), scheduled, or inactivity re-engagement ("no message in X days").
3. Human-intervention cancel / ביטול בוט בהתערבות אנושית (role: human_intervention_cancel) — fires when a human agent sends a message and stops the running bot so it never talks over a human. One is seeded active per org; a package can deploy its own.

Gambot AI (the AI operator) = ownership. To route a contact to Gambot AI, assign the contact's owner to Gambot AI. The Gambot-AI botomation's trigger is contactOwner == the Gambot AI user, so it then answers with a GambotAi step. An activator can therefore do "if no communication in X days → assign the contact to Gambot AI", and the AI takes over.

Building a bot in one call. gambot_deploy_bot_package assembles the whole package for you, in order — (1) main bot, (2) activator, (3) human-intervention cancel — all sharing one sourceFlowId. Pick botType: "menu" (give openingTemplateName + options, and an activator that sends the opening template: keyword / any_message / inactivity / campaign_lead) or botType: "keyword" (self-activating — its keyword IS the activator, so no separate activator is created). AI/combined bots (Gambot AI) are built in the Bot Builder app because they need a Gambot AI configuration.

Turning a bot on/off: gambot_set_bot_status toggles one botomation; pass includePackage: true to turn the whole bot (main + activator + cancel + Gambot AI) on or off together. Use gambot_get_bot_package first to see exactly what will change.

Example prompts

• "Send a WhatsApp to +972 50‑123‑4567 saying their order shipped."
• "Message everyone tagged VIP with the promo_launch template."
• "How many WhatsApp messages did we receive today, and how many are waiting for a reply?"
• "Summarize today's customer‑service conversations."
• "Schedule a campaign to the newsletter tag for tomorrow at 10:00."
• "Build a lead bot: when a lead arrives from an ad, send the welcome_lead template with buttons Sales/Support, and stop if I jump in." → gambot_deploy_bot_package(botType: "menu", openingTemplateName: "welcome_lead", options: [...], activator: { type: "campaign_lead" }).
• "Turn off my lead bot completely (the bot, its trigger and the AI answer)." → gambot_get_bot_package then gambot_set_bot_status(includePackage: true, status: "inactive").
• "Which bots are active, and what triggers each one?" → gambot_list_bots (read role + triggerKind).

Agent behavior, errors & recovery

Gambot MCP is designed so an AI agent can understand what happened and what to do next — it interprets the API's structured business state and returns actionable guidance.

• Structured errors. On an API error the tool result is JSON with a stable machine‑readable code, the human message, the API's data (state flags), and — when recoverable — a recommendedAction naming a real tool. Example:

  config.json

  Copy

  {
    "status": "action_required",
    "code": "CONVERSATION_WINDOW_CLOSED",
    "message": "A free-form WhatsApp message cannot currently be sent.",
    "data": { "canSendFreeText": false, "canSendTemplate": true },
    "recommendedAction": {
      "tool": "gambot_send_template",
      "reason": "The 24-hour window is closed; send an approved template. List options with gambot_list_templates."
    }
  }
  

• Common recoveries. CONVERSATION_WINDOW_CLOSED / TEMPLATE_REQUIRED → gambot_send_template; MISSING_TEMPLATE_VARIABLES → gambot_get_template_variables (then ask the user); CONTACT_NOT_FOUND → gambot_list_contacts (never guess a recipient); RATE_LIMITED / messaging‑limit → back off, don't loop, use a campaign for bulk.

• Safety. The agent never silently picks an ambiguous recipient, and never loops single‑send tools for bulk — it's routed to campaigns.

• Tool annotations. Read tools are marked read‑only/idempotent; delete_*, disable_user and issue_invoice are marked destructive; every tool is openWorld (it talks to the live WhatsApp/Gambot backend). Use these to gate confirmations for external‑communication and high‑impact actions.

REST API & docs

• REST reference, auth, scopes and the full error‑code vocabulary: https://gambot.co.il/developers/
• WhatsApp API for AI agents: https://gambot.co.il/whatsapp-api-for-ai-agents/

Security

The Gambot Token is a secret (like a password). Keep it out of source control (use the client's env). You can rotate it any time from Gambot Settings → General, and optionally narrow its scopes there.

Publishing (maintainers)

This package ships with a server.json manifest for the official MCP Registry (registry.modelcontextprotocol.io). The registry only stores metadata, so the npm package must be published first, and the reverse‑DNS name in server.json must match mcpName in package.json (io.github.gambot-ai/gambot-mcp).

# 1) Publish the npm package (public)
npm publish --access public

# 2) Install the registry publisher CLI
#    (see https://modelcontextprotocol.io/registry/quickstart)
brew install mcp-publisher            # or download from the registry releases

# 3) Authenticate under the io.github.gambot-ai/* namespace and publish
mcp-publisher login github
mcp-publisher publish

If your GitHub owner is not gambot-ai, update the name in server.json, mcpName in package.json, and the repository/identifier fields to match before publishing.

Once listed in the official registry, aggregators such as Glama, PulseMCP and Smithery index the server automatically. A smithery.yaml is also included for Smithery.