Come collegare Xentral a Gemini via MCP

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

Xentral + Gemini

Collega Xentral ERP alla tua AI: cerca articoli e giacenze per magazzino e ubicazione, clienti e fornitori, ordini di vendita, documenti di trasporto con tracking, fatture con stato di pagamento, note di credito, ordini d'acquisto e fatture dei fornitori, e crea bozze di ordini di vendita. Con l'API attuale di Xentral e un Personal 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:

XENTRAL_URL, XENTRAL_TOKEN

Step 1 — Ottieni le credenziali

1. In Xentral clicca su Administration in basso a sinistra, poi su Account settings (Kontoeinstellungen) → Developer settings (Developer Einstellungen) → Personal Access Tokens. Più rapido: digita "Personal Access Token" nella Smart Search. Serve un account admin.
2. Clicca su Create token (Token erzeugen) e dai al token un nome come AnythingMCP-Read, una descrizione e una durata (di default 180 giorni).
3. Concedi Read sulle aree che l'AI deve vedere: articoli e giacenze, clienti (CRM), documenti di vendita (ordini di vendita, documenti di trasporto, fatture, note di credito), acquisti (ordini d'acquisto, fornitori, debiti verso fornitori) e impostazioni come metodi di pagamento e progetti. Aggiungi Create e Delete sugli ordini di vendita solo se l'AI può preparare bozze d'ordine. Escludi gli scope Admin.
4. Clicca su Create e copia subito il token: Xentral lo mostra una sola volta.
5. Imposta XENTRAL_URL sull'indirizzo con cui apri Xentral, per esempio https://acme.xentral.biz (o il tuo dominio), senza /api, senza percorso e senza barra finale. Inserisci il token da solo in XENTRAL_TOKEN, senza la parola Bearer, poi installa il connettore.
6. Comincia con xentral_list_products: se tornano degli articoli, URL e token funzionano.

Durata e permessi del token: un token scade alla data che hai scelto, e Xentral elimina i token non usati da 180 giorni. I permessi non si possono modificare in seguito: per cambiarli crea un nuovo token e sostituisci XENTRAL_TOKEN. L'AI vede solo le aree che il token può leggere.

Id, non numeri stampati: ogni strumento richiede l'id interno di Xentral, non il numero di articolo, documento o cliente stampato. L'AI trova prima l'id con uno strumento di elenco, con un filtro su number, documentNumber o customerNumber, oppure con search. L'id di un cliente è anche il suo id indirizzo: i documenti lo mostrano come address.id, e xentral_create_sales_order lo richiede come addressId. I filtri sui clienti trovano solo corrispondenze esatte, quindi per trovare un cliente da una parte del nome l'AI cerca i suoi documenti con xentral_list_invoices o xentral_list_sales_orders e prende address.id da lì.

Filtri: gli strumenti di elenco accettano condizioni che devono valere tutte, ognuna con un campo (key), un operatore (op) e un valore (value). Le fatture aperte, per esempio: [{"key": "paymentStatus", "op": "in", "value": ["pending", "partiallyPaid"]}]. Tra gli operatori ci sono equals, in, contains, startsWith, greaterThanOrEquals e lessThan; ogni strumento indica i campi che accetta. Le date dei documenti sono nel formato YYYY-MM-DD.

Cercare e ordinare i documenti: per ordini di vendita, documenti di trasporto, fatture, note di credito e ordini d'acquisto, search cerca nel numero del documento, nel nome e nel numero del cliente o del fornitore, nell'email, nel CAP e nei numeri d'ordine esterni. sort accetta nomi di campo, un meno davanti ordina in modo decrescente (-documentDate), e include aggiunge dati collegati come lineItems (righe) o address.

Stati: gli ordini di vendita sono draft, released, completed o cancelled; fatture, documenti di trasporto e ordini d'acquisto possono anche essere sent. Lo stato di pagamento (paymentStatus) di fatture e note di credito è pending, paid, partiallyPaid, cancelled, partiallyCancelled, badDebt o debited.

Giacenze: xentral_get_product_stock restituisce i totali e gli stessi valori per magazzino e per canale di vendita. sellable è quanto si può ancora promettere a un cliente, physical quanto c'è sugli scaffali, reserved quanto è impegnato dagli ordini aperti. I magazzini (Lager) contengono ubicazioni (Lagerplätze): xentral_list_product_storage_locations mostra dove si trova un articolo, xentral_list_storage_location_items cosa c'è in un'ubicazione.

Spedizioni e pagamenti: xentral_list_delivery_note_shipments restituisce corriere, numero di tracking e link di tracking di un documento di trasporto. xentral_get_invoice_balance mostra i pagamenti registrati su una fattura e quanto resta aperto.

Pagine: gli elenchi di documenti accettano page e perPage (fino a 1000, 25 di default); gli altri elenchi page e pageSize (da 10 a 50).

Scrittura: xentral_create_sales_order crea solo una bozza per un cliente esistente: senza numero d'ordine, e nulla viene riservato o spedito finché qualcuno non la controlla e la rilascia in Xentral. Se l'AI non indica i prezzi, Xentral usa quelli del cliente e dell'articolo. xentral_delete_sales_order_draft elimina una bozza di questo tipo ed è disattivato all'installazione; Xentral rifiuta di eliminare ordini rilasciati, completati o annullati. Tutti gli altri strumenti leggono soltanto.

Solo lettura: dai al token solo permessi Read e disattiva xentral_create_sales_order nella pagina del connettore.

Limite di frequenza: Xentral consente circa 100 richieste al minuto per istanza, qualunque sia il piano; oltre risponde 429 con un header Retry-After. Meglio un solo elenco filtrato che tante ricerche singole.

Errori comuni: 401 significa che il token è sbagliato, scaduto o eliminato. 403 significa che al token manca il permesso per quell'area: crea un nuovo token che lo abbia. 400 "Generic request validation failed" o "filter must be an array" indica un campo di filtro o un operatore che lo strumento non accetta, oppure un valore malformato. 404 "Route not found" significa che XENTRAL_URL contiene un percorso come /api/v1, o che l'istanza non offre ancora quell'endpoint. 409 durante l'eliminazione di un ordine di vendita significa che non è più una bozza.

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

Tool disponibili

Esempi di prompt

• "Quante unità dell'articolo 700123 possiamo ancora vendere in ogni magazzino, e in quali ubicazioni si trova?"
• "Quali fatture sono ancora da pagare o pagate solo in parte? Mostrami cliente, importo e livello di sollecito, dalle più vecchie."
• "Dov'è il pacco dell'ordine 200345? Dammi il corriere e il link di tracking."
• "Crea una bozza di ordine di vendita per il cliente 10001 con 20 pezzi dell'articolo 700123 e 5 pezzi dell'articolo 700456, data di consegna desiderata 20 ottobre."

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