Come collegare Square a Gemini via MCP

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

Square + Gemini

Fai lavorare la tua AI con la tua attività su Square: consulta pagamenti, rimborsi e ordini, gestisci i clienti, cerca e modifica il catalogo articoli, controlla le giacenze, crea e invia fatture e vedi sedi e membri del team. Sandbox o produzione, con il tuo access token.

Prerequisiti

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

SQUARE_ACCESS_TOKEN, SQUARE_API_URL

Step 1 — Ottieni le credenziali

1. Accedi a developer.squareup.com/apps con il tuo account Square e clicca su Create an application (il nome non conta).
2. Apri l'applicazione e vai su Credentials. Il selettore in alto passa da Sandbox a Production e viceversa.
3. Accanto all'Access token dell'ambiente che ti serve, clicca su Show, copia il token e inseriscilo in SQUARE_ACCESS_TOKEN, senza la parola Bearer e senza spazi.
4. Imposta SQUARE_API_URL su https://connect.squareupsandbox.com per un token sandbox o su https://connect.squareup.com per un token di produzione, senza barra finale. Un token funziona solo nel proprio ambiente.
5. Installa il connettore ed esegui square_get_merchant: mostra nome, paese e valuta dell'attività raggiunta dal token.

Access token: il token della pagina Credentials è un access token personale con accesso completo al tuo account Square, ed è proprio quello che serve al connettore. Non scade, ma chiunque lo possieda può agire per conto della tua attività: tienilo segreto e, se finisce in mani sbagliate, sostituiscilo nella stessa pagina e inserisci quello nuovo in SQUARE_ACCESS_TOKEN.

Sandbox e produzione: il token sandbox appartiene a un venditore di prova predefinito, quindi non ci sono né soldi né clienti reali. Per vedere i risultati come venditore, apri nella developer console Sandbox test accounts → l'account → Square Dashboard. La sandbox non invia mai fatture per email; apri invece il link pubblico della fattura.

Permessi e solo lettura: il token della pagina Credentials ha sempre accesso completo, quindi la sola lettura si imposta nel connettore: disattiva square_refund_payment, square_create_order, square_create_customer, square_update_customer, square_upsert_catalog_object, square_create_invoice, square_publish_invoice e square_cancel_invoice.

Disattivati all'installazione: square_delete_customer, square_delete_catalog_object e square_delete_invoice. Attivali solo se l'AI deve eliminare profili cliente, oggetti del catalogo (un articolo insieme alle sue varianti) o bozze di fattura (anche il relativo ordine viene annullato).

Soldi ed email ai clienti: square_refund_payment restituisce denaro al cliente e non si può annullare, square_publish_invoice invia la fattura al cliente per email e la rende pagabile, e square_cancel_invoice blocca il pagamento di una fattura pubblicata e avvisa il cliente. Prima di usarli, l'AI indica importo, cliente e id e aspetta il tuo sì. Fa lo stesso prima di modificare un articolo esistente del catalogo con square_upsert_catalog_object.

Fatture: una fattura si basa su un ordine aperto. L'AI crea l'ordine con square_create_order (non viene addebitato nulla), poi una bozza con square_create_invoice; al cliente non arriva niente finché non esegue square_publish_invoice. Per l'invio via email il profilo cliente deve avere un indirizzo email.

Le modifiche al catalogo sostituiscono l'intero articolo: square_upsert_catalog_object sostituisce un oggetto esistente per intero, quindi l'AI legge prima l'articolo con square_get_catalog_object e rimanda la copia completa; i campi omessi, varianti comprese, verrebbero eliminati. Le giacenze sono tenute per variante e sede, non per articolo.

Sedi: la maggior parte dei dati appartiene a una sede, e square_list_locations le mostra tutte. Senza sede, square_list_payments copre solo la sede principale, e le fatture sono sempre elencate per sede. Gli ordini registrati offline possono comparire fino a 72 ore dopo.

Errori comuni: 401 UNAUTHORIZED significa che il token è sbagliato o non corrisponde a SQUARE_API_URL (un token sandbox con l'URL di produzione o viceversa): controlla entrambi. 403 significa che al token manca un permesso per la chiamata; un token della pagina Credentials ha accesso completo, quindi verifica di aver inserito proprio quello. 400 VERSION_MISMATCH significa che l'oggetto è cambiato nel frattempo e va riletto; le altre risposte 400 INVALID_REQUEST_ERROR indicano il campo non valido. 404 NOT_FOUND significa id sbagliato, oppure un oggetto di un'altra sede o di un altro ambiente. 429 RATE_LIMITED significa che Square sta limitando le richieste dell'account: attendi un momento e riprova.

Il connettore non accetta pagamenti con carta e non gestisce carte regalo, programmi fedeltà, prenotazioni, abbonamenti, accrediti o webhook.

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 Square.

Tool disponibili

Esempi di prompt

• "Quali pagamenti abbiamo incassato ieri nella sede principale, e qualcuno è stato rimborsato?"
• "Trova la cliente [email protected] e mostrami i suoi ordini degli ultimi tre mesi."
• "Quante confezioni di Espresso Blend 1 kg abbiamo in magazzino in ogni sede?"
• "Crea una fattura per Acme Srl per 3 ore di consulenza a 90 EUR l'una, con scadenza il 1° novembre, e mostramela prima di inviarla."

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
• Collegare a Cursor
• Collegare a Meta Muse