Fatture in Cloud MCP Server

Server MCP (Model Context Protocol) per Fatture in Cloud: gestire la fatturazione elettronica italiana — emesse, passive, invio a SDI, situazione contabile — via conversazione, su più aziende dallo stesso server.

Requisiti

• Node.js 18+
• Claude Desktop, Claude Code o altro client MCP
• Un token API di Fatture in Cloud per ogni azienda (vedi sotto)

Installazione

Non serve installare nulla a mano: il client MCP scarica il pacchetto con npx (vedi Configurare il client MCP). I comandi di configurazione dei token si lanciano allo stesso modo:

npx -y @gliz/fic-mcp add-token     # aggiunge il token di un'azienda
npx -y @gliz/fic-mcp tokens        # elenca le aziende configurate

Richiede Node.js 18+ nel PATH (lo stesso che serve a qualsiasi server MCP basato su npx).

1. Ottenere un token (per azienda)

Il server usa un token per azienda, generato collegando l'applicazione Gliz MCP a quella singola azienda. Un token di un account commercialista non funziona: dà accesso solo all'elenco delle aziende, non ai loro dati.

1. Accedi a Fatture in Cloud nel contesto dell'azienda
2. Impostazioni → Applicazioni collegate
3. Collega l'applicazione Gliz MCP (client id nckmwHHZyvCpbtDe1DiNkW3NhPa6eK0r)
4. Da Gestisci genera un token manuale con i permessi necessari (fatture, clienti, fornitori, prima nota…)
5. Copia il token (formato a/xxxxx.yyyyy.zzzzz)

Ripeti per ogni azienda che vuoi gestire.

2. Configurare i token

I token si aggiungono con un comando: non passano mai da un file di configurazione scritto a mano. Il comando chiede il token (senza mostrarlo a schermo), verifica su quale azienda dà accesso e lo salva.

npx -y @gliz/fic-mcp add-token       # chiede il token, scopre l'azienda, salva
npx -y @gliz/fic-mcp tokens          # elenca le aziende configurate
npx -y @gliz/fic-mcp tokens --check  # verifica che i token siano ancora validi

I token vengono salvati in:

| Sistema | Percorso | |---------|----------| | macOS / Linux | ~/.config/fic-mcp/accounts.json | | Windows | %APPDATA%\fic-mcp\accounts.json |

Override del percorso con la variabile d'ambiente FIC_CONFIG.

Il file contiene token in chiaro. Su macOS/Linux è scritto con permessi 0600. Su Windows è protetto dalle ACL della cartella profilo.

3. Configurare il client MCP

Claude Desktop

Modifica ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) o %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "fattureincloud": {
      "command": "npx",
      "args": ["-y", "@gliz/fic-mcp"]
    }
  }
}

Poi riavvia completamente Claude Desktop.

Claude Code

claude mcp add --transport stdio fattureincloud -- npx -y @gliz/fic-mcp

Uso

Con una sola azienda configurata, i comandi funzionano senza altro:

"Mostrami le fatture di dicembre 2025"
"Qual è la situazione contabile del 2025?"
"Quali fatture devo ancora incassare?"

Con più aziende, ogni richiesta deve indicare l'azienda (nome, alias o id). Chiedi prima list_companies per vedere quali sono:

"Elenca le aziende configurate"
"Fatture 2025 di GLIZ"
"Situazione contabile di VISIO"

Strumenti disponibili

Interroga il server con list_companies per l'elenco aziende, e usa gli altri tool per fatture emesse e passive, clienti e fornitori, prima nota, anagrafiche IVA e centri di costo, situazione contabile, invio a SDI ed email. L'elenco completo e aggiornato dei tool è quello che il client MCP mostra alla connessione.

Sicurezza

• Le operazioni di scrittura (creazione fatture, invio a SDI, modifiche) richiedono sempre conferma prima di essere eseguite.
• L'invio allo SDI è irreversibile.
• Le fatture vengono create come bozze.
• L'aliquota IVA di ogni articolo va indicata con l'id del tipo IVA aziendale (vat_id), non con la percentuale: su Fatture in Cloud l'aliquota è determinata dall'id. Usa list_vat_types per risolverlo.

Sviluppo

git clone [email protected]:glizsrl/fic-mcp.git
cd fic-mcp
npm install
npm run build      # compila in dist/
npm test           # test (node:test via tsx)
npm run dev        # esegue da sorgente con tsx

La documentazione dell'SDK Fatture in Cloud e le convenzioni del progetto sono in CLAUDE.md.

Licenza

Software proprietario. Copyright © 2026 Gliz S.r.l. — tutti i diritti riservati. Vedi LICENSE. La pubblicazione su npm serve alla sola distribuzione a chi ne ha titolo e non costituisce una licenza open source.

Basato sul progetto Python originale fattureincloud-mcp di Mediaform s.c.r.l..