gambot-mcp

# Gambot MCP Server — WhatsApp API for AI agents

[![npm](https://img.shields.io/npm/v/gambot-mcp)](https://www.npmjs.com/package/gambot-mcp)
[![MCP Registry](https://img.shields.io/badge/MCP-Registry-blue)](https://registry.modelcontextprotocol.io)
[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](./LICENSE)

Connect **WhatsApp** to **Claude, ChatGPT, Gemini and Cursor**. This is a [Model Context Protocol](https://modelcontextprotocol.io) 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](cursor://anysphere.cursor-deeplink/mcp/install?name=gambot&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsImdhbWJvdC1tY3AiXSwiZW52Ijp7IkdBTUJPVF9UT0tFTiI6IiJ9fQ==) — then paste your Gambot token into the server's `env`.

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:

| What you need | Build on Meta Cloud API yourself | Gambot (this server) |
| --- | --- | --- |
| Onboarding | Meta app review + Business verification, WABA setup | Guided onboarding, live in ~24–48h |
| Phone number | Register/migrate & manage via API | Connect/migrate from the dashboard (Coexistence supported) |
| Templates | Submit via API, track approval, version | Visual editor + approval status; `gambot_list_templates` |
| Webhooks | Host a public HTTPS endpoint (retries, dedupe, scale) | Managed inbound events; optional forwarding |
| Media | Upload/host media, manage ids/expiry | Handled in messages, templates & campaigns |
| 24h window | Track each conversation; choose free-text vs template | Enforced; API returns `CONVERSATION_WINDOW_CLOSED` + `canSendTemplate` |
| Tiers & limits | Track tiers, throttle, handle 131xxx errors | Handled; structured limit errors |
| Campaigns | Build queueing, segmentation, opt-out, reporting | Native campaigns with consent & per-recipient results |
| Automation / CRM | Build a bot engine & contact store | Bots, CRM, consent/opt-out & spam handling built in |
| **AI agents** | Parse raw Graph API errors (brittle) | **Machine-readable states + MCP recommended next actions** |
| API upkeep | Migrate as Meta bumps Graph versions | Gambot absorbs Meta API changes |

**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+
- A Gambot Token (`gmbt_…`) from the Gambot admin panel → **Settings → General**.

## 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`)

```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`).

## Local development (from source)

```bash
npm install
npm run build
```

Then point your MCP client at the built entrypoint:

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

## Tools

| Group | Tools |
|-------|-------|
| Messages | `gambot_send_text`, `gambot_send_template` |
| Conversations | `gambot_list_conversations` (the conversation/contact LIST — who, with last-message metadata only), `gambot_get_conversation_messages` (full message history of ONE conversation), `gambot_analytics_transcript` (message CONTENT across ALL conversations for a period — for "how did my team reply today / which customers were upset"), `gambot_check_window` (is the 24h window open? → free text vs template), `gambot_list_numbers` (sender numbers for multi-number orgs) |
| Templates | `gambot_list_templates`, `gambot_get_template`, `gambot_get_template_variables`, `gambot_create_template` (text/media header, body variables, footer, buttons), `gambot_upload_template_media` |
| Contacts | `gambot_get_contact_fields`, `gambot_create_contact`, `gambot_list_contacts` (list/search the whole contacts directory — by name/phone/email, tag, conversation status/category or owner), `gambot_get_contact`, `gambot_update_contact` (base + `customFields`), `gambot_list_ctwa_contacts` (contacts created from a Click-to-WhatsApp ad, with the originating ad info) |
| Leads | `gambot_get_lead_fields`, `gambot_create_lead`, `gambot_list_leads`, `gambot_get_lead`, `gambot_update_lead` (all base fields + `customFields`) |
| Cases | `gambot_get_case_fields`, `gambot_create_case`, `gambot_list_cases`, `gambot_get_case`, `gambot_update_case` (base + `customFields`) |
| Tasks | `gambot_create_task`, `gambot_list_tasks`, `gambot_get_task`, `gambot_update_task` |
| Notes | `gambot_list_notes` (read/search the notes across contacts, leads & cases — the in-app "Notes Hub"; filter by source/date/author/text), `gambot_get_entity_notes` (notes for one contact/lead/case) |
| Analytics / reports | `gambot_analytics_summary` (one-shot KPI snapshot: messages, contacts, leads, tickets, tasks, bots), `gambot_analytics_messages`, `gambot_analytics_overview` (lifetime + 6-month trend), `gambot_analytics_daily_conversations` (daily time series), `gambot_analytics_contacts`, `gambot_analytics_leads`, `gambot_analytics_cases`, `gambot_analytics_tasks`, `gambot_analytics_ctwa`, `gambot_analytics_bots` (bot/automation run performance + per-bot breakdown) |
| Quotes | `gambot_create_quote`, `gambot_list_quotes`, `gambot_get_quote`, `gambot_update_quote` |
| Invoices | `gambot_create_invoice`, `gambot_list_invoices`, `gambot_get_invoice`, `gambot_update_invoice`, `gambot_issue_invoice` |
| Orders | `gambot_create_order`, `gambot_list_orders`, `gambot_get_order`, `gambot_update_order` |
| Signatures | `gambot_list_signatures`, `gambot_get_signature`, `gambot_get_signature_link` (signing link to distribute) |
| Web forms | `gambot_list_forms`, `gambot_get_form`, `gambot_get_form_link` (public link to distribute), `gambot_get_form_submissions` |
| Document templates | `gambot_list_documents`, `gambot_get_document`, `gambot_create_document_link` (distributable fill link), `gambot_get_document_submissions` |
| Users | `gambot_create_user`, `gambot_list_users`, `gambot_get_user`, `gambot_update_user`, `gambot_enable_user`, `gambot_disable_user` |
| Campaigns | `gambot_list_campaigns`, `gambot_list_scheduled_campaigns`, `gambot_get_campaign`, `gambot_get_campaign_results`, `gambot_create_campaign` (SAVED campaign — use for ANY scheduled send (once/recurring is always a campaign) or a reusable CRM-segment broadcast), `gambot_send_campaign_from_excel` (mail-merge blast from a sheet the user gave you — pass rows + phoneColumn + column→variable mapping; **an Excel broadcast is always saved as a campaign** — immediate = save + run now, scheduled = save + scheduler runs it), `gambot_update_campaign`, `gambot_delete_campaign`, `gambot_run_campaign`, `gambot_send_campaign` (immediate "run to a group": ad-hoc, unsaved send to a tag/segment/phone list), `gambot_test_campaign` (single recipient). **Decision rule:** group-run = immediate & unsaved (`gambot_send_campaign`); scheduled (once/recurring) = always a campaign (`gambot_create_campaign`); one-time Excel = always a campaign (`gambot_send_campaign_from_excel`). Prefer a **template** for broadcasts — a `regular` free-text broadcast only reaches recipients whose 24h window is open. **Compliance is built in:** every org has an ACTIVE opt-out flow (recipients reply `הסר`/`stop`/`unsubscribe` → excluded from future broadcasts); send/run responses echo it under `optOut` (enabled by default) and your consent under `consent`. |
| Bots & automations | `gambot_deploy_bot_package` (**build a WHOLE bot in one call** — main bot + activator + human-intervention cancel, linked as one package), `gambot_list_bots`, `gambot_get_bot`, `gambot_get_bot_package` (the whole bot: main + activator + human-intervention cancel + Gambot AI), `gambot_create_keyword_autoreply`, `gambot_create_template_button_autoreply`, `gambot_create_menu_bot`, `gambot_create_bot` (advanced, full step schema), `gambot_set_bot_status` (on/off; `includePackage` toggles the whole bot), `gambot_delete_bot` |
| Onboarding | `gambot_check_organization`, `gambot_generate_organization_name`, `gambot_search_availa