Fatture in Cloud MCP

Server MCP per Fatture in Cloud: porta in Claude fatture, rate, incassi, clienti e situazione economica, e copre 117 delle 123 operazioni dell'API v2 (conti di saldo, metodi di pagamento e recupero dal cestino restano, per sicurezza, solo nell'app web). Parte in sola lettura; scrittura e invio si attivano solo se lo scegli, e ogni scrittura chiede anteprima e una tua conferma esplicita, data fuori dalla chat.

English below

Progetto indipendente, non ufficiale: non è affiliato né approvato da TeamSystem o da Fatture in Cloud, marchi dei rispettivi titolari.

Cosa puoi chiedere a Claude

• "Elenca le fatture di ottobre 2026"

• "Quali rate sono scadute e non pagate? Raggruppale per cliente"

• "Dettaglio della fattura 33/2026"

• "Situazione dell'anno, mese per mese"

• "Ecco i movimenti dell'estratto conto di settembre: quali bonifici corrispondono a rate aperte?"

• Con la modalità write: "segna pagata la seconda rata della fattura 33/2026, bonifico del 10 ottobre", "duplica la fattura 41 con data di oggi sostituendo settembre con ottobre", "converti la proforma 12 in fattura"

• Con la modalità full e FIC_ENABLE_SEND=true: "invia la fattura 35 allo SDI", "manda al cliente la copia di cortesia"

Related MCP server: freee MCP Server

Installazione

Serve Node.js 20 o superiore solo per l'uso da riga di comando: Claude Desktop ha già il suo.

Claude Desktop (consigliato)

1. Scarica fattureincloud-mcp-server-<versione>.mcpb dalla pagina Releases.

2. Aprilo con un doppio clic (oppure Impostazioni > Estensioni > Impostazioni avanzate > Installa estensione).

3. Inserisci il token di Fatture in Cloud (vedi sotto). Il token viene salvato nel portachiavi del sistema.

4. Lascia la modalità su readonly finché non ti serve altro.

Riga di comando (Linux, macOS, Windows)

FIC_ACCESS_TOKEN=... npx -y fattureincloud-mcp-server@1.4.0

Oppure dal codice sorgente:

git clone https://github.com/almostnine/fattureincloud-mcp.git
cd fattureincloud-mcp
npm ci --ignore-scripts && npm run build
FIC_ACCESS_TOKEN=... node dist/index.js

Verifica rapida della configurazione: FIC_ACCESS_TOKEN=... node dist/index.js check.

Configurazione manuale di Claude Desktop o di un altro client MCP

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

Il file di Claude Desktop è ~/Library/Application Support/Claude/claude_desktop_config.json su macOS. Con questa configurazione il token sta in chiaro nel file: l'installazione .mcpb lo tiene invece nel portachiavi.

Il token di Fatture in Cloud

Il server usa un token personale (autenticazione manuale, https://developers.fattureincloud.it/docs/authentication/manual-authentication/):

1. In Fatture in Cloud: Impostazioni > Sviluppatore > Nuova app. L'app nasce privata: aggiungi la tua email tra gli utenti autorizzati e annota il Client ID.

2. Impostazioni > Applicazioni collegate > Collega una nuova applicazione: incolla il Client ID, scegli l'azienda e i permessi (scope), poi copia l'Access Token.

3. Il token non scade, ma puoi revocarlo o cambiarne i permessi dalla stessa pagina.

Permessi consigliati per modalità

La modalità del server e i permessi del token sono due protezioni indipendenti: con un token :r nessuna scrittura passa, qualunque sia la modalità.

Attenzione: lo scope issued_documents.invoices:a serve per creare fatture e segnare le rate pagate, ma permette tecnicamente anche l'invio allo SDI. Fatture in Cloud non distingue i due permessi: il blocco degli invii è nel server (FIC_ENABLE_SEND spento di default).

Come si conferma una scrittura

Dalla versione 1.2.0 nessuna scrittura parte senza il tuo sì, dato fuori dalla chat:

1. Claude chiama il tool e riceve solo un'anteprima (per i documenti, le rate e le anagrafiche dry_run vale true di default) con il testo esatto dell'operazione e un token.

2. Claude ti mostra l'anteprima. Se gli dici di procedere, richiama il tool con il token (e dry_run: false).

3. Il server ti chiede la conferma direttamente, su un canale che Claude non può usare:

   • in Claude Desktop con l'elicitation MCP: compare una richiesta con il testo dell'anteprima e la casella "Confermo", da spuntare e inviare;

   • se il client non supporta l'elicitation, su macOS si apre una finestra di sistema con il testo e i pulsanti "Annulla" (predefinito) e "Conferma", che si chiude da sola dopo 2 minuti senza fare nulla;

   • altrimenti la scrittura viene rifiutata.

Il token lega la conferma al corpo esatto mostrato nell'anteprima: se qualcosa cambia, serve una nuova anteprima. Vale una volta e scade dopo 10 minuti. Con FIC_CONFIRM_METHOD scegli il canale (auto, elicitation, dialog, host). Il default resta auto.

Conferma nella chat (FIC_CONFIRM_METHOD=host)

Solo se lo imposti tu. Serve agli host che non hanno l'elicitation MCP e non possono aprire una finestra di macOS, e in cui il sì lo dai nella chat: per esempio Grok Bot su Linux, che mostra l'anteprima e ha anche un proprio livello di approvazione delle chiamate. In Claude Desktop lascia auto.

Con host il server non mostra finestre e non usa l'elicitation. Restano i due passi: anteprima, poi esecuzione con dry_run: false e il token (corpo esatto, un solo uso, 10 minuti). L'anteprima dice all'assistente di mostrarti il testo e di richiamare il tool solo dopo un tuo sì esplicito nella conversazione. Ogni scrittura eseguita così viene registrata su stderr.

Avvio su stdio:

FIC_ACCESS_TOKEN=... FIC_MODE=write FIC_CONFIRM_METHOD=host node dist/index.js

Nella configurazione MCP dell'host le stesse variabili vanno in env del server. Senza FIC_CONFIRM_METHOD, o con auto, non cambia nulla: se non c'è un canale fuori banda la scrittura viene rifiutata.

Coordinate bancarie: il server non invia mai IBAN, banca o beneficiario a Fatture in Cloud. I documenti usano solo il metodo di pagamento configurato nell'account (payment_method_id); un IBAN in note, righe o altri campi viene rifiutato. Conti di saldo e metodi di pagamento si gestiscono solo dall'app web.

Configurazione

Tool

Sola lettura (sempre disponibili)

Scrittura (FIC_MODE=write, ognuno con anteprima e conferma umana)

Invio (FIC_MODE=full e FIC_ENABLE_SEND=true)

L'elenco completo delle operazioni API e del tool che le espone è in docs/COVERAGE.md.

Sicurezza

• Sola lettura di default: in readonly i tool di scrittura e di invio non vengono registrati.

• Ogni scrittura e ogni azione irreversibile (documenti, rate, anagrafiche, scritture generiche, invio SDI, email, cancellazioni, webhook) parte da un'anteprima e, di default, si esegue solo dopo la tua conferma fuori banda (elicitation di Claude Desktop o finestra di macOS), che Claude non può dare al posto tuo. Il token dell'anteprima è legato al corpo esatto, vale una volta e scade dopo 10 minuti, ma da solo non basta. Con FIC_CONFIRM_METHOD=host la finestra non c'è: il sì è quello dato in chat e il token resta obbligatorio.

• Mai IBAN: nessun corpo con coordinate bancarie esce dal server; i documenti usano solo il metodo di pagamento configurato.

• Invii spenti di default: fic_send_einvoice e fic_send_email esistono solo in full con FIC_ENABLE_SEND=true; senza, il client HTTP rifiuta qualsiasi invio allo SDI o per email, da qualunque tool.

• Cancellazioni spente di default: fic_delete esiste solo con FIC_ENABLE_DELETE=true.

• In Claude Desktop non scegliere "consenti sempre" per i tool di invio e di cancellazione: così l'ultima parola resta a te.

• Email solo verso gli indirizzi del cliente in anagrafica o configurati: difesa contro istruzioni nascoste nei documenti dei fornitori.

• Testi da Fatture in Cloud delimitati con ⟦ ⟧ e trattati come dati.

• Nessuna telemetria, un solo host contattato (api-v2.fattureincloud.it), token mai nei log, nessun dato personale nella cache su disco.

Dettagli in SECURITY.md e PRIVACY.md.

Limiti noti

• L'API v2 non ha operazioni per il calendario (Scadenziario Plus) né per i movimenti di magazzino: il magazzino compare solo nei campi dei prodotti e nei documenti.

• L'invio allo SDI, anche in prova, funziona solo con un piano a pagamento.

• I webhook si possono gestire ma non ricevere: servirebbe un endpoint HTTPS pubblico.

• Limiti dell'API: 300 richieste ogni 5 minuti per azienda (condivise con le altre app collegate), 1.000 all'ora, 40.000 al mese. Il server lavora in serie, si limita da solo a 300 richieste ogni 5 minuti, si ferma quando restano meno di 20 richieste nell'ora o nel mese e lo dice quando legge dati parziali.

• Alcuni comportamenti dell'API non sono documentati e sono verificati sull'account di prova: lo stato è in docs/REVIEW.md.

Sviluppo

npm ci --ignore-scripts
npm run check            # lint, type check, test
npm run build            # dist/index.js
npm run pack:mcpb        # pacchetto .mcpb
npm run coverage:doc     # rigenera docs/COVERAGE.md
npm run gen              # rigenera il catalogo dall'OpenAPI (serve reference/openapi-fattureincloud)

Test di integrazione, disattivati di default (leggono .env, mai committato):

• FIC_IT_READONLY=1 npm run test:integration: sola lettura sull'account reale; ogni richiesta che non sia GET viene bloccata in rete.

• FIC_IT_TRIAL=1 FIC_IT_TRIAL_TOKEN=... FIC_IT_TRIAL_COMPANY_ID=... npm run test:integration: scritture solo su un account Trial; il test si ferma se il piano dell'azienda non è trial.

Progettazione e analisi: docs/ANALISI.md, docs/DESIGN.md. Evoluzioni future (tra cui l'uso dall'app Claude sul telefono): docs/ROADMAP.md.

Ringraziamenti

Scritto da zero. Grazie a aringad/fattureincloud-mcp di Mediaform s.c.r.l., studiato come spunto, e a Fatture in Cloud per l'OpenAPI pubblica.

Licenza

MIT

Fatture in Cloud MCP (English)

An MCP server for Fatture in Cloud, the Italian invoicing platform. It brings invoices, installments, payments, clients and financial summaries into Claude and covers 117 of the 123 operations of the v2 API (payment accounts, payment methods and bin recovery are left to the web app on purpose). It starts read-only: write and send capabilities are opt-in, and every write requires a preview plus an out-of-band human confirmation.

Independent, unofficial project, not affiliated with or endorsed by TeamSystem or Fatture in Cloud.

Installation

• Claude Desktop: download the .mcpb from Releases, double-click it, paste your Fatture in Cloud token (stored in the OS keychain), keep the mode on readonly.

• Command line (Node.js 20+): FIC_ACCESS_TOKEN=... npx -y fattureincloud-mcp-server@1.4.0, or build from source with npm ci --ignore-scripts && npm run build && node dist/index.js.

• Manual client config: see the JSON example above (command, args, env).

Token

Create a private app in Fatture in Cloud (Settings > Developer > New app, add your email to the allowed users), then Settings > Connected applications > Connect a new application, paste the Client ID, pick the company and the scopes, copy the access token. Recommended scopes: :r only for readonly; :a on the resources you want to change for write; the same for full, where SDI sending also requires a paid plan.

Modes

Every write is two-step: the tool first returns a preview (dry_run defaults to true) and a token; when called again with the token, the server asks you directly, through MCP elicitation in Claude Desktop or, if the client lacks it, a native macOS dialog ("Annulla" is the default button). The model cannot answer that prompt. Without a human channel the write is refused. Choose the channel with FIC_CONFIRM_METHOD (auto, elicitation, dialog, host). The default stays auto.

FIC_CONFIRM_METHOD=host is opt-in, for a host that confirms in its own chat and has neither MCP elicitation nor a macOS dialog (Grok Bot on Linux, which also reviews MCP calls). The out-of-band step is skipped. The preview and the token stay: the write runs only with dry_run: false and a valid preview token (exact body, single use, 10 minutes). The preview tells the assistant to show you the text and to call the tool only after your explicit yes in the conversation. Each write authorized this way is logged to stderr. Stdio launch:

FIC_ACCESS_TOKEN=... FIC_MODE=write FIC_CONFIRM_METHOD=host node dist/index.js

Put the same variables in the server env of the host's MCP config. Unset, or auto, nothing changes.

Configuration variables, the tool list and known limitations are in the Italian section above; the full API coverage table is in docs/COVERAGE.md.

Security

Read-only by default; every write needs an out-of-band human confirmation unless FIC_CONFIRM_METHOD=host is set explicitly (then the yes is the one given in chat, and the preview token is still required). The preview token (bound to the exact payload, single use, 10-minute expiry) is never enough on its own in the default modes; the server never sends IBANs or other bank details (documents only reference the configured payment method); deletions are off unless FIC_ENABLE_DELETE=true; sending to SDI and by email is off unless FIC_ENABLE_SEND=true, blocked at the HTTP client too; email only to the client's own addresses; text coming from Fatture in Cloud is delimited and treated as data; no telemetry; one host only; the token never appears in logs. Do not pick "always allow" in Claude Desktop for send and delete tools. See SECURITY.md and PRIVACY.md.

License

MIT. Written from scratch; thanks to aringad/fattureincloud-mcp (Mediaform s.c.r.l.) for the inspiration.