> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mattone.co/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP WhatsApp: problemi e domande frequenti

> Il testo esatto di ogni errore comune dell'MCP WhatsApp, perché succede, cosa fare e come verifichi che è risolto. Mac e Windows.

Questa pagina è pensata per **non dover chiedere in giro**: per ogni problema trovi il messaggio
che vedi, il motivo, il passo per risolverlo e come controlli che ha funzionato. Se il tuo caso
non è qui, scrivilo in `#mattone-team` — vedi in fondo.

## macOS blocca lo script

<Accordion title="«Impossibile aprire “installa.command” perché proviene da uno sviluppatore non identificato»">
  **Perché succede:** lo script non ha una firma Apple a pagamento (Developer ID). macOS blocca
  per prudenza qualunque script scaricato da internet la prima volta che lo apri.

  **Cosa fare:**

  1. Al messaggio, clicca **Fine** (non Sposta nel Cestino).
  2. Apri **Impostazioni di Sistema → Privacy e sicurezza**, scorri fino in fondo.
  3. Accanto a *"installa.command" è stato bloccato* clicca **Apri comunque**.
  4. Inserisci la password del Mac e conferma **Apri**.

  Su versioni di macOS più vecchie basta un clic destro sul file → **Apri** → **Apri** nella
  finestra che compare.

  **Come verifichi:** si apre una finestra del Terminale con scritto *"Collegamento di WhatsApp a
  questo Mac"*. Se non si apre nulla, il file è stato spostato dalla cartella del kit: riestrai lo
  zip.
</Accordion>

## uv mancante (Mac e Windows)

<Accordion title="«Manca un programma che serve: uv»">
  **Perché succede:** `configura-claude.command`/`configura-claude.ps1` usa `uv` per preparare i
  componenti Python del collegamento. È un programma separato, non incluso nel kit.

  **Cosa fare:**

  * **Mac**: lo script stampa il comando ufficiale da incollare nel Terminale (da
    [docs.astral.sh/uv](https://docs.astral.sh/uv/)). Incollalo, premi Invio, aspetta che finisca,
    poi rifai doppio clic su `configura-claude.command`.
  * **Windows**: lo script stampa il comando ufficiale da incollare in PowerShell. Eseguilo,
    aspetta che finisca, poi rilancia `configura-claude.ps1`.

  Non serve riavviare il computer; basta chiudere e riaprire il Terminale/PowerShell perché il
  nuovo comando venga trovato.

  **Come verifichi:** rilanciando lo script, la prima riga diventa *"uv trovato: …"* invece di
  fermarsi con l'errore.
</Accordion>

## La porta 8080 è occupata

<Accordion title="Mac — «La porta 8080 è occupata da un altro programma»">
  **Perché succede:** il collegamento usa sempre la porta 8080 per parlare con Claude. Se un altro
  programma la sta già usando (spesso un altro collegamento WhatsApp già avviato, o uno strumento
  di sviluppo lasciato acceso), l'installazione non può ripartire su quella porta.

  **Cosa fare:** lo script elenca il programma che la occupa. Chiudilo (o, se è un collegamento
  WhatsApp installato in precedenza e non ti serve più, esegui prima `disinstalla.command`) e
  rilancia `installa.command`.

  **Come verifichi:** l'installazione prosegue oltre il controllo della porta senza fermarsi.
</Accordion>

<Accordion title="Windows — «La porta 8080 di questo PC è già usata da un altro programma»">
  Stesso motivo e stessa soluzione del Mac qui sopra: chiudi il programma indicato (o disinstalla
  un'installazione precedente con `disinstalla.ps1`) e rilancia `installa.ps1`.

  Se non riconosci il programma indicato, manda uno screenshot di quella finestra in
  `#mattone-team` prima di chiudere qualcosa a caso.
</Accordion>

## Il codice è scaduto

<Accordion title="«WhatsApp non ha dato il codice» oppure il codice non viene accettato sul telefono">
  **Perché succede:** il codice di abbinamento vale solo pochi minuti. Se il telefono resta troppo
  a lungo sulla schermata di inserimento, o la connessione è lenta, scade prima che tu lo inserisca.

  **Cosa fare:** non è un errore, è normale. Rilancia lo script di installazione
  (`installa.command` su Mac, `installa.ps1` su Windows): te ne dà uno nuovo. Tieni il telefono
  sbloccato e con una connessione stabile prima di far partire lo script, così hai tutto il tempo
  per inserirlo.

  **Come verifichi:** compare un nuovo codice a lettere grandi e, dopo averlo inserito sul
  telefono, la scritta **COLLEGATO!**.
</Accordion>

## Il collegamento non risulta collegato (`loggedIn` falso)

<Accordion title="Il collegamento non risponde / non risulta ancora collegato dopo l'abbinamento">
  **Perché succede:** il collegamento vero e proprio con WhatsApp non si è concluso — di solito
  perché il codice è scaduto prima di essere confermato sul telefono, o la connessione è caduta a
  metà.

  **Cosa fare:**

  1. Controlla di aver confermato il collegamento sul telefono (a volte WhatsApp chiede una
     seconda conferma dopo il codice: guarda se c'è una notifica in sospeso).
  2. Se sono passati più di 4 minuti dal codice senza che risultasse collegato, rilancia lo
     script: ne genera uno nuovo.
  3. Se il problema si ripete più volte di fila, esegui `disinstalla.command`/`disinstalla.ps1`,
     cancella la cartella `store` dentro `WhatsAppBridge` e riparti dall'installazione da zero
     (sezione più sotto).

  **Come verifichi:** dopo l'abbinamento riuscito, lo script stampa **«Collegamento attivo»** (o,
  su Windows, **«Collegamento attivo e con avvio automatico»**).
</Accordion>

## Claude Desktop non vede lo strumento WhatsApp

<Accordion title="Tra gli strumenti di Claude Desktop non compare «whatsapp»">
  **Perché succede:** quasi sempre non hai chiuso Claude Desktop **del tutto** dopo aver incollato
  la configurazione — resta attivo in background e continua a usare la configurazione vecchia.

  **Cosa fare:**

  1. **Mac**: chiudi Claude Desktop con **Cmd+Q** (non basta chiudere la finestra), controlla che
     non compaia più nel Dock, poi riaprilo.
  2. **Windows**: chiudi Claude Desktop anche dall'icona vicino all'orologio (tasto destro →
     Esci), non solo dalla finestra, poi riaprilo.
  3. Rilancia `configura-claude.command`/`configura-claude.ps1`: deve dire che la configurazione
     è **già valida**. Se dice il contrario, il testo copiato non è finito nel punto giusto del
     file: segui di nuovo l'indicazione che stampa lo script.

  **Come verifichi:** apri la lista degli strumenti in Claude Desktop e cerca **whatsapp**.
</Accordion>

## Il telefono è rimasto offline più di 14 giorni

<Accordion title="Il tuo Claude ha smesso di vedere messaggi nuovi">
  **Perché succede:** è una regola di WhatsApp, non del kit: se il telefono con il numero
  collegato non viene usato per più di 14 giorni, WhatsApp scollega **tutti** i dispositivi
  collegati, compreso questo.

  **Cosa fare:** riparti dall'installazione da zero (sezione sotto). Non c'è un modo per
  "ricollegare" senza rifare l'abbinamento: è una scelta di sicurezza di WhatsApp.

  **Come verifichi:** dopo aver reinstallato, sul telefono in *Dispositivi collegati* torna a
  comparire **Chrome (Linux)**.
</Accordion>

## Reinstallare da capo

<Accordion title="Come si riparte da zero, su Mac o su Windows">
  Serve quando il telefono si è scollegato da solo (14 giorni offline, o 30 giorni di
  inattività del collegamento), o dopo più tentativi falliti di abbinamento.

  **Mac:**

  1. Doppio clic su `disinstalla.command` (nel kit o dentro `~/WhatsAppBridge`).
  2. Nella cartella **Inizio → WhatsAppBridge**, cancella la cartella `store`.
  3. Rilancia `installa.command` come alla prima installazione.

  **Windows:**

  1. Clic destro su `disinstalla.ps1` → **Esegui con PowerShell**.
  2. In `%USERPROFILE%\WhatsAppBridge`, cancella la cartella `store`.
  3. Rilancia `installa.ps1` come alla prima installazione.

  **Come verifichi:** ottieni un nuovo codice di abbinamento e, dopo averlo inserito, la scritta
  **COLLEGATO!**.
</Accordion>

## Gli strumenti WhatsApp dell'MCP Mattone Platform dicono «non raggiungibile da questa macchina»

<Accordion title="L'MCP Mattone Platform non trova il registro dei messaggi">
  **Perché succede:** l'MCP Mattone Platform cerca l'MCP WhatsApp **sullo stesso computer**. Se
  non lo trova, è quasi sempre uno di questi tre casi:

  * l'MCP WhatsApp non è installato su **questo** computer (magari è installato su un altro);
  * è installato ma non è mai stato **collegato** con un numero (l'abbinamento non è arrivato in
    fondo — vedi *"Il collegamento non risulta collegato"* qui sopra);
  * il collegamento è stato spostato fuori dalla cartella che il kit crea di default.

  **Cosa fare:** installa (o reinstalla nella cartella di default) l'MCP WhatsApp seguendo
  [Installazione — Mac](/riferimenti/whatsapp/installazione-mac) o
  [Installazione — Windows](/riferimenti/whatsapp/installazione-windows), poi chiudi e riapri
  Claude Code: lo trova al riavvio successivo, senza bisogno di reinstallare l'MCP Mattone
  Platform.

  **Come verifichi:** vedi [Collegarlo all'MCP Mattone Platform](/riferimenti/whatsapp/collegare-mattone-platform#come-verifichi-che-si-vedono).
</Accordion>

## Non risolto qui?

Scrivilo in `#mattone-team` con:

* se sei su Mac o Windows;
* il messaggio esatto che vedi (uno screenshot va benissimo, **controlla prima che non si vedano
  chat, numeri o nomi di altre persone**);
* a che passo dell'installazione sei arrivato.

<Info>
  Se una risposta di questa pagina non ti risolve il problema, **dillo in `#mattone-team`**: vuol
  dire che la pagina va corretta o completata. Vedi
  [Manutenzione docs](/riferimenti/manutenzione-docs).
</Info>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.