Aruba Fatture MCP
This server integrates Aruba's electronic invoicing into MCP clients, allowing you to manage invoices, counterparties, and reports using natural language. It connects to three data sources: the Aruba web panel (live, no premium), official APIs (premium required for some features), and local archives (no premium).
What you can do:
Account: Retrieve your VAT number, fiscal code, service status, and storage usage (
get_user_info).Invoice Management:
Search and filter sent/received invoices by period, status, type, and counterparty (premium via APIs, no premium via panel).
View full invoice details (ID, SDI status, notifications) using
get_invoice_detailor panel tools.Download invoices in XML, PDF, ZIP (with SDI notifications), or PDD conservation package (premium via APIs).
Send or validate invoices by uploading XML; default dry-run mode prevents accidental submission, real sending requires explicit opt-in and premium.
Create XML drafts and upload them to the panel (
panel_create_invoice_xml/panel_upload_invoice).
SDI Notifications: Track delivery receipts, rejections, etc. for a specific invoice (no premium needed).
Counterparties: List customers and suppliers, including registry details and activity periods (panel or archive).
Reports:
VAT summaries (separated sales/purchases) and revenue/purchase trends (monthly, quarterly, yearly). Available via
vat_report,revenue_trend, or equivalent panel tools.
Safety & Separation: Sent and received invoices are always kept separate;
send_invoiceusesdryRun=trueby default to prevent accidental SDI transmission.
All functions are accessible through the web panel (no premium) or via APIs (premium required for search, detail, download, and actual sending). Local archives allow offline analysis without premium.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Aruba Fatture MCP Cerca le fatture ricevute la settimana scorsa"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Server Model Context Protocol che porta la Fatturazione Elettronica di Aruba dentro qualsiasi client MCP — Claude (Code e Desktop), Cursor, Cline, Zed e gli altri. Interroghi e crei fatture elettroniche (FatturaPA / SDI) in linguaggio naturale: «quanto ho fatturato quest'anno?», «prospetto IVA del trimestre», «chi sono i miei fornitori principali?», «genera la fattura per questo cliente».
Documentazione API ufficiali Aruba: https://fatturazioneelettronica.aruba.it/apidoc/v2/docs.html
Il server ha tre sorgenti dati indipendenti:
Pannello web (live) — legge le fatture direttamente dal pannello Aruba in tempo reale, senza utenza Premium. È la sorgente consigliata per liste, clienti/fornitori, IVA e statistiche;
API Aruba ufficiali — dati in tempo reale dal web service, ma richiedono un'utenza Premium (o delegata da una Premium);
archivio locale — analisi sugli XML/ZIP esportati a mano, utile offline o come backup.
In tutte le sorgenti, fatture inviate (ciclo attivo) e ricevute (ciclo passivo) sono sempre tenute separate: nessun tool le somma o le mischia.
Tool sul pannello web (live, nessuna utenza Premium)
Accedono al pannello con le stesse credenziali del login web, replicandone l'API interna. Non serve esportare nulla: i dati sono sempre aggiornati.
Tool | Descrizione |
| Elenco fatture di un ciclo ( |
| Dettaglio di una singola fattura (metadati + righe + riepilogo IVA); può salvare XML e PDF su disco |
| Clienti (dalle inviate) o fornitori (dalle ricevute), con totali e periodo di attività |
| Registro anagrafico salvato in Aruba: clienti o fornitori, con P.IVA, codice fiscale, codice destinatario e indirizzo |
| Totali IVA dell'anno: IVA vendite e IVA acquisti separate, con il saldo |
| Andamento per mese/trimestre/anno, inviate e ricevute in due serie distinte |
| Genera l'XML di una nuova fattura scegliendo il cliente dal registro Aruba; calcola i totali. Non invia |
| Carica un XML nel pannello creando una bozza pronta da rivedere e inviare. Non invia a SDI |
Ogni tool di elenco/anagrafica richiede il parametro ciclo (o tipo) proprio per non mescolare mai i due flussi. I dati dell'anno vengono scaricati una volta e messi in cache; ricarica: true forza il riscaricamento.
Creare e inviare una fattura
Il flusso è pensato per essere sicuro rispetto all'unica azione irreversibile — l'invio a SDI:
panel_registrycontipo: "clienti"per trovare il destinatario (o si conosce già la sua P.IVA);panel_create_invoice_xmlgenera l'XML: i dati del mittente sono riusati da una fattura già emessa (sempre corretti), il destinatario dal registro Aruba, e i totali IVA sono calcolati dalle righe. Restituisce il file e i totali da verificare;panel_upload_invoicecarica l'XML nel pannello come bozza.
L'invio a SDI non è automatizzato di proposito. È un'azione irreversibile e, su questo account, Aruba richiede un OTP via SMS per completarla (jsAbilitaOtpCaricaFattura). Dopo l'upload, la bozza va rivista e inviata dal pannello web. È una tutela voluta: nessun tool può far partire una fattura reale senza un passaggio umano.
Questi tool usano l'API privata del pannello, non documentata da Aruba: è più comoda (nessun requisito di utenza) ma può cambiare senza preavviso. Per l'accesso ufficiale e stabile restano i tool «API Aruba» qui sotto, che però richiedono un'utenza Premium.
Related MCP server: Invoicetronic MCP Server
Tool sulle API Aruba
Tool | Descrizione | Utenza richiesta |
| Informazioni account (P.IVA, stato servizio, spazio conservazione) | base |
| Notifiche SDI di una fattura per nome file (consegna, scarto, esiti) | base¹ |
| Invia una fattura XML a SDI — di default | Premium |
| Ricerca fatture inviate o ricevute per periodo, stato, controparte | Premium |
| Metadati completi di una fattura (per | Premium |
| Salva su disco XML, PDF, ZIP (fattura + notifiche) o PDD | Premium |
Le utenze base standalone non hanno le deleghe API (FAW-*): ricerca e dettaglio rispondono 401 (delega FAW-R non presente per le inviate, FAW-IN per le ricevute), l'upload risponde 0093 Errore deleghe — ma solo dopo aver superato la validazione XSD, quindi un errore 0092 su upload non implica che l'invio sia abilitato. ¹L'endpoint notifiche risponde a livello dati con utenza base (verificato con errorCode 0002), ma non è stato possibile verificarlo con una fattura esistente.
Attenzione: il controllo delle deleghe avviene dopo la validazione dei parametri. Una richiesta con una finestra date superiore a 10 giorni risponde 400 anche a un'utenza senza deleghe: per sapere se le deleghe ci sono, interrogare con una finestra valida.
Tool sull'archivio locale
Funzionano su una cartella di fatture esportate dal pannello Aruba (o da qualunque altro portale SDI) e non richiedono utenza Premium. Formati riconosciuti, anche in sottocartelle: .xml, .p7m (firmate CAdES) e .zip che li contengono. I duplicati — stesso emittente, numero e data — vengono unificati.
Tool | Descrizione |
| Elenco fatture filtrabile per direzione, periodo, controparte, tipo documento e importo, con i totali del sottoinsieme |
| Anagrafica clienti e fornitori ricostruita dalle fatture, con numero documenti, totali e periodo di attività |
| Prospetto IVA del periodo: imponibile e imposta per aliquota e natura, separando vendite e acquisti, con il saldo |
| Andamento di fatturato e acquisti per mese, trimestre o anno |
La direzione (emessa/ricevuta) è determinata confrontando il cedente della fattura con la partita IVA e il codice fiscale del titolare, letti automaticamente da get_user_info (con fallback a ARUBA_VAT_CODE / ARUBA_FISCAL_CODE se l'account non è raggiungibile).
vat_report è un prospetto contabile di supporto, non una liquidazione IVA: non tiene conto di detraibilità parziale, reverse charge, split payment o crediti pregressi.
Requisiti
Node.js ≥ 18
Credenziali del servizio Aruba Fatturazione Elettronica
Installazione
npm install
npm run buildConfigurazione
Variabile | Descrizione |
| Username del servizio Fatturazione Elettronica |
| Password del servizio |
|
|
| Cartella con gli XML/ZIP delle fatture, usata dai tool di analisi quando non si passa |
| Facoltativa: P.IVA del titolare, solo come fallback se |
| Facoltativa: codice fiscale del titolare, stesso scopo |
Le credenziali non vanno messe in file versionati: .env è già in .gitignore.
L'ambiente demo usa i server di test Aruba (demoauth/demows): consigliato per le prime prove.
Collegare il server a un client MCP
Il server parla stdio ed è compatibile con qualunque client MCP. La configurazione è sempre la stessa — comando node <percorso>/dist/index.js con le variabili d'ambiente qui sopra. Sotto due esempi (Claude Code e Claude Desktop); per Cursor, Cline, Zed e gli altri vale lo stesso schema command/args/env nel rispettivo file di configurazione MCP.
Claude Code
claude mcp add aruba-fatture ^
-e ARUBA_USERNAME=tuo_username ^
-e ARUBA_PASSWORD=tua_password ^
-e ARUBA_ENVIRONMENT=demo ^
-- node <percorso-del-progetto>\dist\index.jsClaude Desktop
In claude_desktop_config.json (o nel file MCP equivalente di Cursor/Cline/Zed):
{
"mcpServers": {
"aruba-fatture": {
"command": "node",
"args": ["<percorso-del-progetto>\\dist\\index.js"],
"env": {
"ARUBA_USERNAME": "tuo_username",
"ARUBA_PASSWORD": "tua_password",
"ARUBA_ENVIRONMENT": "demo"
}
}
}
}Note operative
Invio a SDI:
send_invoiceper default esegue solo la validazione (dryRun=true). L'invio reale avviene solo chiedendo esplicitamente di impostaredryRun=false.Trasmittente: le fatture inviate tramite Aruba devono riportare l'intermediario Aruba nell'
IdTrasmittente(P.IVA01879020517).Codice destinatario per ricevere fatture su Aruba:
KRRH6B9.Rate limit Aruba: 12 richieste/minuto per le ricerche, 30/minuto per gli upload; oltre soglia il server restituisce HTTP 429. Anche l'endpoint di autenticazione è soggetto a rate limit severi: il client serializza i login e riusa i token proprio per questo — in caso di 429 sull'autenticazione attendere qualche minuto.
I contenuti base64 (XML/PDF) vengono omessi dalle risposte testuali per non saturare il contesto: usare
download_invoiceper salvarli su file.I token di accesso (30 min) e di refresh (60 min) sono gestiti automaticamente.
Architettura
Il codice è organizzato per sorgente dati, in modo che i tre canali restino indipendenti.
File | Ruolo |
| Server MCP: registra tutti i tool e li instrada alla sorgente giusta |
| Login headless al pannello (OpenID Connect) e chiamate all'API interna |
| Normalizzazione e aggregazione dei dati del pannello (inviate/ricevute separate) |
| Client delle API ufficiali (OAuth2 password/refresh, gestione token) |
| Lettura di un archivio locale di |
| Parser FatturaPA v1.2.x da XML a struttura tipizzata |
| Aggregazioni sull'archivio locale (liste, controparti, IVA per aliquota, andamento) |
Come funziona la modalità pannello (live)
Il pannello web di Aruba non espone API documentate, ma la sua interfaccia parla con un backend REST interno (/services/*) dietro un login OpenID Connect (Keycloak). Il client replica il flusso di login del browser senza browser:
GET /api/oauth2/authorization/gateway→ il gateway reindirizza a Keycloak e imposta il cookie di sessione;si legge la pagina di login Keycloak e se ne estrae l'
actiondel form;POSTdi username e password all'action→ risposta con l'authorization code(il reCAPTCHA della pagina non è imposto lato server);il ritorno del
codeal gateway stabilisce la sessione applicativa.
Da qui le chiamate /services/* usano il cookie di sessione più gli header applicativi aru-sub, aru-delegator e X-Requested-With che il pannello aggiunge. Il login viene serializzato e la sessione riusata; alla scadenza (401) si rifà il login e si ritenta una volta. I dati dell'anno sono scaricati una volta e messi in cache in memoria.
È un'API privata e non documentata: funziona con qualunque utenza (nessun requisito Premium) ma Aruba può cambiarla senza preavviso. In quel caso restano operative le altre due sorgenti.
Validazione XSD locale
In test/ c'è una fattura di esempio e gli schemi XSD ufficiali FatturaPA v1.2.2. Per validare un XML senza passare dall'API (equivalente strutturale del dryRun):
pip install xmlschema
python -c "import xmlschema; s = xmlschema.XMLSchema('test/xsd/fatturapa.xsd', locations={'http://www.w3.org/2000/09/xmldsig#': 'test/xsd/xmldsig-core-schema.xsd'}); s.validate('test/esempio-fattura.xml'); print('VALIDA')"Esempi di richieste (pannello live)
«Quanto ho fatturato quest'anno? E quanto ho speso in acquisti?»
«Fammi il prospetto IVA del 2026»
«Elenca le fatture inviate di luglio»
«Chi sono i miei fornitori principali?»
«Ci sono fatture inviate scartate da SDI?»
«Confronta fatturato e acquisti trimestre per trimestre»
Come popolare l'archivio locale
Dal pannello Aruba Fatturazione Elettronica, sezione fatture inviate/ricevute, si esportano i documenti del periodo in ZIP. Basta salvare gli ZIP (senza scompattarli) in una cartella e puntarci ARUBA_ARCHIVE_DIR: i tool di analisi leggono direttamente il contenuto.
Con un'utenza Premium lo stesso archivio si popola via API con download_invoice in formato zip.
Esempi di richieste
Sulle API (utenza Premium):
«Cerca le fatture ricevute la settimana scorsa»
«Ci sono fatture scartate da SDI a luglio? Mostrami il motivo dello scarto»
«Scarica il PDF della fattura IT01234567890_00042 in C:\fatture»
«Valida questo XML prima dell'invio» (usa
send_invoicecondryRun=true)
Sull'archivio locale (qualsiasi utenza):
«Quanto ho fatturato nel secondo trimestre?»
«Fammi il prospetto IVA da gennaio a giugno»
«Chi sono i miei 10 clienti principali per fatturato?»
«Mostrami le fatture ricevute sopra i 1.000 euro»
«Confronta il fatturato mese per mese di quest'anno»
Available Tools
6 toolsdownload_invoiceScarica fattura su fileBRead-only
Scarica una fattura su disco nel formato scelto: xml (il file fattura originale), pdf (versione leggibile), zip (fattura + notifiche SDI), pdd (pacchetto di distribuzione della conservazione, disponibile solo se pddAvailable=true nel dettaglio).
Inputs: format (required), direction (required), outputPath (required), id, +2 more.
get_invoice_detailDettaglio fatturaARead-only
Restituisce i metadati completi di una singola fattura (mittente, destinatario, stato, notifiche SDI). Identificarla con uno tra id, filename o idSdi. Per scaricare XML/PDF/ZIP usare download_invoice.
Inputs: direction (required), id, idSdi, filename.
get_invoice_notificationsNotifiche SDI di una fatturaARead-only
Restituisce le notifiche SDI di una singola fattura a partire dal nome file (es. ricevuta di consegna, scarto, mancata consegna). Funziona anche con utenza base: è il modo per tracciare lo stato di una fattura inviata via API (il filename è restituito da send_invoice come uploadFileName).
Inputs: direction (required), invoiceFilename (required).
get_user_infoInfo account ArubaARead-only
Restituisce le informazioni dell'account Aruba Fatturazione Elettronica: partita IVA, codice fiscale, stato del servizio, spazio di conservazione utilizzato.
Inputs: no named parameters.
search_invoicesRicerca fattureARead-only
Cerca fatture elettroniche inviate (ciclo attivo) o ricevute (ciclo passivo) su Aruba Fatturazione Elettronica, filtrando per periodo, stato, tipo documento e controparte. Risultati paginati. NOTA: richiede un'utenza Premium (o delega da Premium); con utenza base risponde 401 per mancanza di deleghe.
Inputs: direction (required), creationEndDate (required), creationStartDate (required), page, +10 more.
send_invoiceInvia fattura a SDIA
Carica una fattura elettronica XML su Aruba per l'invio al Sistema di Interscambio (SDI). ATTENZIONE: con dryRun=false la fattura viene inviata realmente a SDI. Per default dryRun=true: il file viene solo validato, senza invio. Il file XML deve indicare come trasmittente l'intermediario Aruba (IdTrasmittente 01879020517). Fornire il file tramite xmlFilePath (consigliato) oppure xmlContent.
Inputs: dryRun, signed, senderPIVA, xmlContent, +1 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 6 tools
Each tool targets a clearly distinct purpose: account info, searching, detail retrieval, downloading, sending, and notifications. The overlap between get_invoice_detail and get_invoice_notifications is minimal since one returns metadata while the other returns SDI notifications. download_invoice is clearly distinguished from get_invoice_detail by its download focus.
Tools follow a consistent verb_noun pattern: get_user_info, search_invoices, get_invoice_detail, download_invoice, send_invoice, get_invoice_notifications. The verbs (get/search/download/send) are consistent and descriptive. Minor stylistic inconsistency exists in user_info (underscore) vs invoice tools being all snake_case but readable.
Six tools is a well-scoped set for an e-invoicing service covering the core lifecycle. Not overly heavy or thin for the domain, though a few more could be expected (e.g., managing uploads or listing all uploads), but this feels within reason.
The set covers the core invoicing workflow: retrieving user info, searching, getting details, downloading files, sending, and checking notifications. Minor gaps exist—there's no tool to manage/update the account, cancel invoices, or list uploads as a whole—but the essential active/passive cycle workflows are covered.
Maintenance
Related MCP Connectors
MCP server for Quaderno — tax-rate calculation, invoices, contacts, products, receipts & expenses.
MCP server for Codat — companies, connections, invoices, bills and financial statements.
MCP server unifying ERPs, CRMs, APIs and knowledge base for Claude, ChatGPT and Gemini.
MCP server for ABRA Flexi — accounting, contacts, stock and draft-checked invoice creation.
Related MCP Servers
- AlicenseAqualityBmaintenanceModel Context Protocol (MCP) server for Italian Electronic Invoicing (FatturaPA / SDI). Provide tools to validate, generate, and explore API specifications for Sistema di Interscambio (SDI) interoperability.4393 PyPI2Apache 2.0
- AlicenseAqualityDmaintenanceMCP server for Italian electronic invoicing via the Invoicetronic API, enabling management of invoices through SDI with 20 tools for sending, receiving, exporting, and more.18MIT
- AlicenseNot gradedqualityDmaintenanceMCP server for integrating VeriFactu (AEAT) with Claude Code and Cursor, enabling generation, chaining, and sending of electronic invoicing records via natural language.MIT
- AlicenseAqualityCmaintenanceMCP server for POP — enabling LLMs to generate, submit, and manage Italian e-invoices (FatturaPA/SdI), Peppol invoices, and PDF invoices directly from AI assistants.1689 npmMIT