Come collegare Zoho Books a Gemini via MCP

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

Zoho Books + Gemini

Fai lavorare la tua AI in Zoho Books: cerca e gestisci clienti, fornitori e articoli, crea, invia per email, segna come inviate e annulla le fatture, crea preventivi, registra pagamenti dei clienti, fatture dei fornitori e spese, e leggi il piano dei conti, i mastrini e i movimenti bancari. Qualsiasi data center Zoho, accesso con OAuth di Zoho.

Prerequisiti

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

ZOHO_BOOKS_CLIENT_ID, ZOHO_BOOKS_CLIENT_SECRET, ZOHO_BOOKS_ORGANIZATION_ID, ZOHO_BOOKS_ACCOUNTS_URL, ZOHO_BOOKS_API_URL

Step 1 — Ottieni le credenziali

1. Individua il tuo data center Zoho: lo vedi nella barra degli indirizzi quando usi Zoho Books (per esempio books.zoho.eu o books.zoho.com). Imposta ZOHO_BOOKS_ACCOUNTS_URL e ZOHO_BOOKS_API_URL su quel data center, senza barra finale: https://accounts.zoho.eu e https://www.zohoapis.eu per l'UE, https://accounts.zoho.com e https://www.zohoapis.com per gli Stati Uniti. India, Australia, Giappone, Arabia Saudita, Emirati Arabi Uniti e Cina seguono lo stesso schema (.in, .com.au, .jp, .sa, .ae, .com.cn); il Canada usa https://accounts.zohocloud.ca e https://www.zohoapis.ca.
2. Apri la Zoho API Console su api-console.zoho.com, con l'accesso del tuo account Zoho, e scegli Add Client → Server-based Applications.
3. Dai un nome al client (per esempio AnythingMCP), indica il sito della tua azienda come homepage URL e https://cloud.anythingmcp.com/api/mcp-oauth/callback come Authorized Redirect URI. Se ospiti AnythingMCP in proprio, inserisci invece https://tuo-host-anythingmcp/api/mcp-oauth/callback. Crea il client.
4. Nella scheda Client Secret copia il Client ID (inizia con 1000.) e il Client Secret in ZOHO_BOOKS_CLIENT_ID e ZOHO_BOOKS_CLIENT_SECRET. Se la tua organizzazione Books si trova in un data center diverso da quello in cui si è aperta la console, abilita quel data center nella scheda Settings del client (Multi-DC) e usa il client secret indicato lì.
5. Trova l'ID dell'organizzazione: in Zoho Books clicca sul nome dell'organizzazione (in alto a destra) e apri Manage Organizations; l'ID compare accanto a ogni organizzazione. Inserisci le cifre in ZOHO_BOOKS_ORGANIZATION_ID. Un connettore lavora con una sola organizzazione; per una seconda installalo di nuovo.
6. Installa il connettore, clicca su Authorize with Provider nella pagina del connettore, accedi a Zoho e approva l'accesso richiesto.
7. Esegui zoho_books_list_organizations e controlla che il tuo ID organizzazione sia nell'elenco, poi zoho_books_get_organization per verificare nome e valuta di base prima che l'AI legga o scriva qualsiasi cosa.

Restare connessi: gli access token durano un'ora e vengono rinnovati automaticamente con il refresh token salvato, che non scade finché non viene revocato. Zoho conserva al massimo 20 refresh token per utente e client: autorizzare lo stesso client per la 21ª volta, in AnythingMCP o altrove, revoca in silenzio il più vecchio. Se il connettore perde l'accesso, clicca di nuovo su Authorize with Provider.

Permessi e solo lettura: il connettore richiede ZohoBooks.settings.ALL, ZohoBooks.contacts.ALL, ZohoBooks.invoices.ALL, ZohoBooks.estimates.ALL, ZohoBooks.customerpayments.ALL, ZohoBooks.bills.ALL, ZohoBooks.expenses.ALL, ZohoBooks.accountants.READ, ZohoBooks.banking.READ. Articoli, imposte e impostazioni dell'organizzazione rientrano in ZohoBooks.settings, il piano dei conti in ZohoBooks.accountants. Lavora come l'utente Zoho che lo ha autorizzato, nei limiti del suo ruolo. Per un setup in sola lettura, cambia ogni .ALL in .READ nelle impostazioni OAuth del connettore, autorizza di nuovo e disattiva zoho_books_create_contact, zoho_books_update_contact, zoho_books_mark_contact_inactive, zoho_books_create_item, zoho_books_update_item, zoho_books_mark_item_inactive, zoho_books_create_invoice, zoho_books_email_invoice, zoho_books_mark_invoice_sent, zoho_books_void_invoice, zoho_books_mark_invoice_draft, zoho_books_create_estimate, zoho_books_create_customer_payment, zoho_books_create_bill e zoho_books_create_expense.

Disattivati all'installazione: i tool di eliminazione zoho_books_delete_contact, zoho_books_delete_invoice, zoho_books_delete_estimate, zoho_books_delete_customer_payment, zoho_books_delete_bill e zoho_books_delete_expense. Un record eliminato non si può recuperare, quindi attivane uno solo se l'AI deve davvero eliminare quel tipo di record.

Le scritture sono reali: zoho_books_email_invoice invia un'email al cliente dalla tua organizzazione, zoho_books_mark_invoice_sent e zoho_books_void_invoice modificano la contabilità, e zoho_books_create_customer_payment, zoho_books_create_bill e zoho_books_create_expense registrano in contabilità generale. L'AI dice prima cosa sta per registrare o inviare e aspetta il tuo sì. Registrare un pagamento di un cliente è solo contabilità: non viene incassato denaro.

Fatture e correzioni: una nuova fattura è una bozza numerata dalla numerazione automatica della tua organizzazione e viene inviata per email solo se chiedi di spedirla subito. Zoho rifiuta di eliminare una fattura inviata: annullala invece con zoho_books_void_invoice. Una fattura annullata resta agli atti, come richiedono regole contabili quali le GoBD tedesche, e zoho_books_mark_invoice_draft la riporta a bozza modificabile da correggere e riemettere.

Totali e saldi: Zoho non documenta un'API dei report per Books. Per i totali l'AI legge i saldi dal piano dei conti, i movimenti di un conto con zoho_books_list_account_transactions o elenchi filtrati per data.

Limiti: 100 richieste al minuto per organizzazione e, al giorno, 1.000 con Free, 2.000 con Standard, 5.000 con Professional e 10.000 da Premium in su. Oltre il limite Zoho risponde 429 (codice 44 al minuto, 45 al giorno): attendi un minuto, o il giorno dopo.

Errori comuni: invalid_client all'accesso o un elenco di organizzazioni vuoto significa che i due URL non sono quelli del tuo data center. 401 con codice 57 ("You are not authorized to perform this operation") o invalid_oauthtoken significa che all'accesso manca uno scope, che è stato revocato o che ZOHO_BOOKS_API_URL è il data center sbagliato: controlla entrambi gli URL, poi clicca di nuovo su Authorize with Provider. 400 o 404 che citano l'organizzazione significano che ZOHO_BOOKS_ORGANIZATION_ID è errato o non visibile a questo utente: confrontalo con zoho_books_list_organizations. Gli altri errori 400 indicano il campo (un nome duplicato, un valore non valido, un campo obbligatorio mancante). Il codice 4529 significa che una fattura inviata non si può eliminare: annullala. Il codice 3000 quando elimini un contatto significa che fatture o pagamenti fanno ancora riferimento a esso: usa zoho_books_mark_contact_inactive.

Il connettore non gestisce ordini di vendita, ordini di acquisto, note di credito, pagamenti ai fornitori, registrazioni di prima nota, progetti, fatture ricorrenti, allegati o PDF.

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 Zoho Books.

Tool disponibili

Esempi di prompt

• "Quali fatture sono scadute e quanto ci deve ancora ogni cliente?"
• "Mostrami il saldo del conto di spesa Cancelleria e tutti i movimenti di settembre."
• "Crea una bozza di fattura per Acme Srl: 12 ore di Consulenza a 95 EUR, scadenza a 14 giorni. Non inviarla ancora."
• "Registra il bonifico di oggi di 1.140 EUR da Acme Srl come pagamento della fattura INV-000123."

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