Fatture in Cloud

fattureincloud-mcp

Server MCP per [Fatture in Cloud](https://www.fattureincloud.it): gestisci la fatturazione parlando con Claude (o con qualsiasi client MCP) invece di cliccare nell'interfaccia.

Fa quello che l'app non fa:

• Fatture ricorrenti. «Ogni 5 del mese rifai la fattura ad Acme con il mese precedente nell'oggetto, inviala allo SdI e mandala per email.» Fatture in Cloud non ha una funzione nativa per farlo.
• Duplicazione vera. Copia una fattura con nuova data, numero successivo, scadenze ricalcolate, bollo e conto di pagamento, cambiando solo le righe che vuoi.
• Operazioni in blocco. Duplicare, inviare allo SdI, mandare per email o segnare come pagate decine di fatture con un comando, con anteprima obbligatoria prima di agire.
• Controlli e report. Crediti scaduti per cliente, fatturato e incassato per mese, distanza dalla soglia del forfettario (85.000 €, principio di cassa), bollo mancante, fatture elettroniche non inviate o scartate, buchi nella numerazione.
• Riconciliazione bancaria. Carichi l'estratto conto (Intesa, UniCredit, Fineco, BPER, Poste, ING, Revolut, N26, Qonto o qualsiasi CSV/XLSX), oppure colleghi il conto via PSD2, e ogni bonifico viene abbinato alla fattura giusta e registrato come incasso con la sua data.
• Previsione di cassa. Mese per mese: incassi attesi, fatture ricorrenti, scadenze fiscali e spese fisse, con quanto accantonare ogni mese per arrivare coperto a giugno e novembre.
• Pacchetto per il commercialista. Un solo zip con CSV, PDF, XML e riepilogo dell'anno.
• Tasse del forfettario. Imposta sostitutiva e contributi INPS stimati dagli incassi reali: quanto pagare il 30 giugno (saldo e 1° acconto) e il 30 novembre (2° acconto), il totale annuo e la percentuale da accantonare.
• Tutta l'API v2. Documenti emessi e ricevuti, clienti, fornitori, prodotti, corrispettivi, F24, archivio, prima nota, allegati, cestino, impostazioni. Quello che non ha un tool dedicato passa da api_request.

English: MCP server for the Italian invoicing SaaS Fatture in Cloud. Recurring invoices, real document duplication, bulk e-invoice (SdI) sending, receivables and *regime forfettario* reports, plus full CRUD over the v2 API. Tool descriptions are in Italian because the domain is Italian.

Esempi di cose da chiedere

• «Rifai tutte le fatture di settembre con la data di oggi, fammi vedere l'anteprima.»
• «Imposta la fattura mensile per Acme il giorno 5, importo fisso, inviala allo SdI e per email.»
• «Chi mi deve ancora pagare? Segna come pagata la 26, incassata ieri.»
• «Quanto mi manca alla soglia del forfettario? A questo ritmo la supero?»
• «Trasforma la proforma 12 in fattura elettronica e verifica l'XML.»
• «Ci sono fatture sopra 77,47 € senza bollo?»
• «Scarica i PDF delle fatture di ottobre in ~/Documenti/fatture.»
• «Quante tasse pago il 30 giugno e il 30 novembre? Quanto devo accantonare per ogni fattura?»
• «Ecco l'estratto conto di Intesa (~/Downloads/movimenti.xlsx): segna come pagate le fatture incassate.»
• «A novembre avrò abbastanza sul conto per l'acconto? Quanto metto da parte al mese?»
• «Metti le scadenze fiscali nel mio calendario e negli F24 di Fatture in Cloud.»
• «Prepara il pacchetto 2026 per il commercialista.»
• «Registra le fatture dei fornitori arrivate dallo SdI, con la categoria giusta. Quali spese ricorrenti sono aumentate?»

Installazione

Serve Node.js 20 o superiore.

1. Token

In Fatture in Cloud:

1. Apri Impostazioni → App e API (area sviluppatori) e crea un'applicazione privata, ad esempio mcp-fattureincloud.
2. In «Autenticazione e accesso» spunta solo «Token personale» e togli OAuth 2.0: così il Redirect URL non serve. Salva.
3. Dalla pagina dell'app genera il token: scegli l'azienda e i permessi. Servono almeno lettura e scrittura su documenti emessi e clienti; per report e tasse basta la lettura sul resto; aggiungi la scrittura sulle altre risorse che vuoi gestire.
4. Copia il token: non viene più mostrato. Non incollarlo in chat. Mettilo nella configurazione del client MCP o in ~/.config/fattureincloud-mcp/.env.

I token personali non scadono e si revocano dalla stessa pagina (guida ufficiale).

2. Client MCP

Claude Desktop, con un clic. Scarica fattureincloud-mcp-x.y.z.mcpb dall'ultima release, aprilo con doppio clic e incolla il token quando te lo chiede. Non serve modificare file di configurazione, e il token viene salvato nel portachiavi di sistema.

Claude Code

claude mcp add --scope user fattureincloud -e FIC_ACCESS_TOKEN=il-tuo-token -- npx -y fattureincloud-mcp

Configurazione manuale (claude_desktop_config.json, Cursor, Windsurf e simili):

{

"mcpServers": { "fattureincloud": { "command": "npx", "args": ["-y", "fattureincloud-mcp"], "env": { "FIC_ACCESS_TOKEN": "il-tuo-token" } } } }

Altri esempi in examples/. Finché il pacchetto non è su npm, al posto di fattureincloud-mcp usa github:NiccoloSalvini/fattureincloud-mcp.

Variabili

Le variabili possono stare anche in ~/.config/fattureincloud-mcp/.env, nella forma FIC_ACCESS_TOKEN=.... È il modo consigliato per il job pianificato.

Fatture ricorrenti

Fatture in Cloud non ha la pianificazione, quindi le ricorrenze vivono sul tuo computer, in ~/.config/fattureincloud-mcp/schedules.json, e un job giornaliero le esegue.

1. Chiedi a Claude di crearne una, ad esempio con il prompt nuova_ricorrenza. Ogni ricorrenza ha:

• un documento modello, che viene copiato a ogni scadenza;
• una cadenza: ogni N mesi, un certo giorno, dove 31 significa l'ultimo del mese;
• un'azione: create lascia la fattura da controllare e inviare (consigliato se l'importo cambia), create_and_send_sdi verifica l'XML e la invia;
• l'email facoltativa al cliente;
• le modifiche: righe, importi e testi con segnaposto.

1. Installa il job (una volta sola):

   npm i -g fattureincloud-mcp

   fattureincloud-mcp install-scheduler --hour 8

Su macOS crea un LaunchAgent che gira ogni mattina e manda una notifica con l'esito. Se il Mac era in stop parte al risveglio; se era spento, la fattura viene creata alla prima esecuzione successiva. Su Linux stampa la riga da mettere in crontab.

Comandi utili:

fattureincloud-mcp schedules

fattureincloud-mcp run-due --dry-run

Segnaposto utilizzabili in oggetto, note e righe: {{mese}}, {{anno}}, {{mese_precedente}}, {{anno_mese_precedente}}, {{mese_successivo}}, {{trimestre}}, {{data}}. Aggiungi |maiuscolo per la maiuscola iniziale. Per esempio Consulenza {{mese_precedente}} {{anno_mese_precedente}} diventa, il 5 novembre, «Consulenza ottobre 2026».

Garanzie:

• Ogni ricorrenza produce al massimo un documento per scadenza: la prossima data viene salvata *prima* di creare la fattura, e un lock impedisce esecuzioni sovrapposte tra il job e Claude. Se qualcosa va storto la fattura manca, non viene duplicata, e l'errore resta nello storico.
• Se il computer è rimasto spento per più periodi, al riavvio viene creato un solo documento, datato oggi, e non uno per ogni periodo arretrato. La numerazione resta così in ordine cronologico.
• Se la verifica dell'XML fallisce, la fattura viene creata ma non inviata, e l'errore viene segnalato.

Strumenti

123 tool divisi in gruppi, attivabili con FIC_TOOLSETS. Il gruppo admin è sempre attivo.

documents: documenti emessi

• list_/get_/create_/update_/delete_issued_document(s)
• duplicate_document: copia con nuova data, numero, scadenze e modifiche
• transform_document: proforma → fattura, preventivo → ordine o fattura, DDT → fattura
• join_documents: unisce più DDT, ordini o preventivi in un solo documento
• mark_paid / mark_unpaid
• email_document
• verify_einvoice, send_einvoice (con dry_run), get_einvoice_xml, einvoice_rejection_reason
• create_credit_note: nota di credito totale o parziale, collegata alla fattura originale come richiede lo SdI
• preview_totals: totali calcolati da Fatture in Cloud (rivalsa, IVA, ritenute, bollo, rate) senza creare il documento; li usa anche l'anteprima di duplicate_document
• get_document_pdf: link o download
• upload_attachment
• get_new_document_defaults: prossimi numeri e valori predefiniti
• list_deleted_documents, recover_document

automation: in blocco e ricorrenze

• bulk_duplicate, bulk_send_einvoice, bulk_email: dry_run attivo di default; accettano una lista di id o un filtro
• schedule_create, schedule_list, schedule_get, schedule_update, schedule_delete
• schedule_run_due, schedule_run_now

reports

• receivables_report: crediti aperti, scaduto per fasce, per cliente
• revenue_summary: fatturato (competenza) e incassato (cassa) per mese e cliente, soglia del forfettario con proiezione
• audit_documents: fatture elettroniche non inviate o scartate, bollo mancante, pagamenti scaduti, numerazione
• client_statement: estratto conto di un cliente

taxes

• tax_profile_set, tax_profile_get: coefficiente, aliquota, previdenza, versamenti reali
• tax_estimate: scadenze del 30 giugno e del 30 novembre, totale annuo, quota da accantonare
• regime_simulator: forfettario contro ordinario contro SRL sui tuoi numeri
• stamp_duty_report: bollo virtuale per trimestre (F24 codici 2521-2524); entra anche nelle scadenze
• quadro_lm: valori del quadro LM della dichiarazione per un anno chiuso

planning

• cashflow_forecast: previsione di cassa e accantonamento mensile
• tax_deadlines_export: scadenze fiscali in .ics e negli F24 di Fatture in Cloud
• accountant_package: zip annuale per il commercialista

bank

• bank_reconcile: abbina gli accrediti alle fatture e registra gli incassi
• bank_parse_statement, bank_formats
• bank_link_start, bank_link_finish, bank_accounts, bank_list_banks: collegamento PSD2 via Enable Banking

registry

• CRUD su clients, suppliers, products, e sulle impostazioni payment_accounts, payment_methods, vat_types
• client_from_vat: anagrafica da partita IVA via VIES, con città e provincia verificate
• lookup_city: comuni da CAP o nome
• list_price_lists, get_price_list_items

received: fatture passive e spese

• CRUD su received_documents (spese, note di credito passive)
• list_pending_received_documents, get_pending_received_document: fatture dei fornitori arrivate dallo SdI e in attesa di registrazione
• register_pending_received_documents: le registra come spese, con categoria, rate e pagamento (dry_run attivo di default)
• suggest_expense_categories: categoria proposta dallo storico del fornitore o da parole chiave
• recurring_expenses_report: fornitori ricorrenti, prossima fattura attesa, totale annuo, aumenti di prezzo

accounting: receipts_monthly_totals, e CRUD su receipts (corrispettivi), f24, `archive_docum