Come collegare Chatwoot a Gemini via MCP

💡 Niente installazione? Vai direttamente su cloud.anythingmcp.com. Accedi, clicca Connectors → Chatwoot, inserisci le credenziali, genera una MCP API key e hai finito. Niente Docker, niente git clone, niente server locale.

Chatwoot + Gemini

Chatwoot, la inbox di supporto omnicanale, in cloud o self-hosted: conversazioni e messaggi da WhatsApp, e-mail, web chat e canali social, contatti, etichette, agenti, team, risposte predefinite e report di supporto (prima risposta, tempi di risoluzione e di risposta). Risposte, note private e nuove conversazioni sono incluse, ma disattivate all'installazione.

Prerequisiti

Le istruzioni di setup complete sono incluse nel connettore stesso (visibili nello store quando lo selezioni). Le variabili d'ambiente richieste sono:

CHATWOOT_URL, CHATWOOT_API_TOKEN, CHATWOOT_ACCOUNT_ID

Step 1 — Ottieni le credenziali

La configurazione richiede circa 2 minuti. Ti serve un account Chatwoot, su Chatwoot Cloud o self-hosted, e l'access token dell'utente con cui l'AI deve lavorare.

1. Accedi a Chatwoot con quell'utente. Gli agenti vedono solo le conversazioni delle inbox di cui fanno parte e non possono leggere i report, quindi per il quadro completo usa un amministratore.
2. Clicca sul tuo avatar, poi su Profile Settings, e copia l'Access Token in fondo alla pagina in CHATWOOT_API_TOKEN. Non scade; puoi reimpostarlo dalla stessa pagina.
3. Imposta CHATWOOT_URL sull'indirizzo con cui apri Chatwoot: https://app.chatwoot.com su Chatwoot Cloud, oppure il tuo dominio, per esempio https://chat.example.com, se è self-hosted. Niente percorso, niente /app, niente /api.
4. Imposta CHATWOOT_ACCOUNT_ID sul numero dopo /app/accounts/ nella barra degli indirizzi del browser: https://app.chatwoot.com/app/accounts/3/dashboard significa 3.
5. Installa il connettore ed esegui chatwoot_get_profile: mostra l'utente dietro il token, il suo ruolo e tutti gli account che il token raggiunge, con il relativo id.

Token di account, non Platform API: il token di una Platform App di un super admin (/platform/api) qui non funziona. Il connettore usa la Application API di Chatwoot per un account.

Self-hosted dietro nginx: il token viaggia nell'header api_access_token, e nginx scarta gli header con il trattino basso finché non imposti underscores_in_headers on;. Si vede come un 401 a ogni chiamata anche se il token è giusto. Un Chatwoot self-hosted raggiungibile solo in una rete privata non è accessibile da AnythingMCP Cloud; in quel caso usa un AnythingMCP self-hosted dentro quella rete.

Cosa legge: l'account e l'utente dietro il token; le tue inbox (WhatsApp, e-mail, web widget, API, Instagram, Telegram e altre) con i loro membri; agenti e amministratori con la loro disponibilità; i team e i loro membri; etichette, risposte predefinite (canned responses) e definizioni degli attributi personalizzati; le conversazioni con stato, priorità, inbox, etichette, contatto, assegnatario e team, come elenco, come conteggio o con filtri come create dopo una data e assegnate a un agente; i messaggi di una conversazione, comprese note private e allegati; i contatti per nome, e-mail, telefono o identificativo, con tutte le loro conversazioni su ogni inbox; e i report di supporto: totali di un periodo accanto al periodo precedente, una metrica nel tempo, agenti, inbox o team a confronto e cosa è aperto e senza risposta in questo momento. I segreti dei canali delle inbox e l'access token dell'utente vengono rimossi dalle risposte.

Orari e numeri: gli orari di conversazioni e messaggi e i periodi dei report sono timestamp Unix in secondi (UTC), e l'AI li converte prima di citarti un orario. Prima risposta, tempo di risoluzione e tempo di risposta nei report sono in secondi.

Chiede prima di ogni modifica: chatwoot_set_conversation_labels. Chatwoot sostituisce l'intero elenco di etichette di una conversazione, quindi l'AI legge prima le etichette attuali e le invia insieme a quella nuova (o senza quella da togliere). Le etichette devono già esistere nell'account. L'AI ti mostra la conversazione e il nuovo elenco e aspetta il tuo sì.

Disattivati all'installazione: chatwoot_send_message (una risposta, o una nota privata visibile solo agli agenti) e chatwoot_create_conversation. Una risposta o un primo messaggio arriva subito al cliente su WhatsApp, e-mail o chat, quindi un amministratore li attiva consapevolmente. Anche allora l'AI ti mostra il testo e il destinatario e aspetta il tuo sì. Nelle inbox WhatsApp Cloud API il testo libero arriva a un contatto solo entro 24 ore dal suo ultimo messaggio; fuori da questa finestra Chatwoot richiede un modello approvato, che questo connettore non invia.

Limiti: le conversazioni arrivano 25 per pagina, i contatti 15 per pagina e i messaggi 20 alla volta, quindi l'AI scorre le pagine; per un semplice numero conta invece di elencare. Report e statistiche live richiedono il token di un amministratore.

Errori comuni: 401 significa un token sbagliato o reimpostato, oppure nginx che scarta l'header. Un 404 a ogni chiamata di solito indica un CHATWOOT_URL o un CHATWOOT_ACCOUNT_ID sbagliato; un 404 su una sola conversazione indica un id che questo utente non può vedere. I report rispondono 401 o 403 agli agenti che non sono amministratori.

Il connettore non usa la Platform API, non invia modelli WhatsApp, non risolve, riassegna o elimina conversazioni esistenti e non modifica né elimina contatti.

Step 2 — Installa l'adapter

curl -fsSL https://raw.githubusercontent.com/HelpCode-ai/anythingmcp/main/docker-compose.quickstart.yml -o docker-compose.yml
printf 'JWT_SECRET=%s\nENCRYPTION_KEY=%s\n' "$(openssl rand -hex 32)" "$(openssl rand -hex 32)" > .env
docker compose up -d

Step 3 — Aggiungi il connettore in Gemini

L'URL del tuo server: in AnythingMCP apri MCP Servers → il server su cui si trova questo connettore e copia il suo URL (https://cloud.anythingmcp.com/mcp/…). Usalo ovunque questa guida mostra YOUR_SERVER_ID.

Gemini CLI legge i server MCP da ~/.gemini/settings.json (su Windows %USERPROFILE%\.gemini\settings.json). Aggiungi:

{
  "mcpServers": {
    "anythingmcp": {
      "httpUrl": "https://cloud.anythingmcp.com/mcp/YOUR_SERVER_ID",
      "headers": { "X-API-Key": "YOUR_MCP_API_KEY" }
    }
  }
}

1. Crea una chiave API MCP in AnythingMCP da MCP Servers → il tuo server → API keys e incollala al posto di YOUR_MCP_API_KEY.
2. Salva il file e riavvia gemini.
3. Esegui /mcp in Gemini CLI (oppure gemini mcp list dal terminale): anythingmcp dovrebbe risultare connesso.
4. Inizia a scrivere prompt: Gemini CLI ora può chiamare i tool di Chatwoot.

Tool disponibili

Esempi di prompt

• "Quante conversazioni aperte non sono assegnate a nessuno in questo momento, e quali agenti hanno chat senza risposta?"
• "Leggi la conversazione 1284 e riassumimi cosa vuole il cliente e cosa gli abbiamo già promesso."
• "Trova il contatto [email protected] ed elenca tutte le sue conversazioni su WhatsApp ed e-mail."
• "Confronta i nostri agenti negli ultimi 30 giorni: conversazioni gestite, tempo di prima risposta e tempo di risoluzione."
• "Aggiungi l'etichetta rimborso alla conversazione 1284 mantenendo le altre. Mostrami prima il nuovo elenco."

FAQ

Dove cerca i server MCP Gemini CLI? In ~/.gemini/settings.json per il tuo utente, oppure in .gemini/settings.json dentro un progetto. gemini mcp list mostra ogni server e se si connette.

Prossimi passi

• Landing del connettore
• Collegare a Claude
• Collegare a ChatGPT