fic-mcp
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
fic-mcp — server MCP per Fatture in Cloud
Server MCP (Model Context Protocol) che dà a Claude, o a qualsiasi client MCP, accesso completo all'API v2 di Fatture in Cloud: anagrafiche, prodotti, documenti emessi, fattura elettronica/SdI, spese e fatture passive, F24, prima nota, corrispettivi, archivio, impostazioni, webhook, più analisi da CFO calcolate dal server.
93 tool organizzati in 15 gruppi attivabili (75 nel set di default, 41 in sola lettura).
Sicurezza per costruzione: modalità sola lettura,
confirm=trueobbligatorio per eliminazioni, invii SdI ed email al cliente,dry_rundi default sulla fattura guidata, registro delle scritture.Privacy: tokenizzazione reversibile dei dati personali (
FIC_PRIVACY_MODE=tokenize).Limiti API rispettati: retry su 429 con
Retry-Aftere backoff, rinnovo automatico del token OAuth2, quote residue lette dagli header senza consumare richieste.Trasporti stdio (Claude Desktop, Claude Code) e Streamable HTTP con bearer token.
Installazione
Serve Python ≥ 3.11.
git clone https://github.com/nogarasimone/MCP-fattureincloud.git
cd MCP-fattureincloud
uv tool install . # oppure: pipx install . oppure: pip install .
fic-mcp --versionL'unica dipendenza è mcp>=2.3 (SDK ufficiale; porta con sé httpx2, pydantic, starlette, uvicorn).
Related MCP server: Invoice4U MCP
Accesso a Fatture in Cloud
Opzione A – token manuale (uso personale). In Fatture in Cloud: Impostazioni → Applicazioni collegate → Sviluppatori, crea un'app privata, scegli i permessi e genera il token manuale.
mkdir -p ~/.config/fic-mcp
cp .env.example ~/.config/fic-mcp/.env # oppure .env nella cartella da cui lanci il server
# imposta FIC_ACCESS_TOKEN=...
fic-mcp doctor # verifica token, aziende, quoteOpzione B – OAuth2 (app pubblica / SaaS). Registra l'app con Redirect URL
http://localhost:8765/callback, imposta FIC_CLIENT_ID e FIC_CLIENT_SECRET, poi:
fic-mcp auth # apre il browser, salva i token in ~/.config/fic-mcp/tokens.json (permessi 600)
fic-mcp auth --read-only # chiede solo gli scope di letturaL'access token dura 24 ore e viene rinnovato da solo con il refresh token (valido un anno).
Se il token gestisce più aziende imposta FIC_COMPANY_ID oppure usa il tool fic_select_company.
Collegarlo a Claude
Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json su macOS):
{
"mcpServers": {
"fatture-in-cloud": {
"command": "/Users/<utente>/.local/bin/fic-mcp",
"env": {
"FIC_ACCESS_TOKEN": "a/xxxxxxxx",
"FIC_READ_ONLY": "true",
"FIC_PRIVACY_MODE": "off"
}
}
}
}Usa il percorso assoluto restituito da which fic-mcp. Riavvia Claude Desktop dopo la modifica.
Claude Code:
claude mcp add fatture-in-cloud -e FIC_ACCESS_TOKEN=a/xxxx -e FIC_READ_ONLY=true -- fic-mcpRemoto (Streamable HTTP), per un gateway o un client web:
FIC_MCP_HTTP_TOKEN=$(openssl rand -hex 32) fic-mcp serve --transport http --port 8000
# endpoint: http://127.0.0.1:8000/mcp — header: Authorization: Bearer <FIC_MCP_HTTP_TOKEN>Claude Code si collega con un header fisso:
claude mcp add --transport http fatture-in-cloud https://mcp.tuodominio.it/mcp \
--header "Authorization: Bearer <FIC_MCP_HTTP_TOKEN>"I connettori personalizzati di Claude.ai / Claude Desktop richiedono OAuth o nessuna autenticazione, non un bearer fisso: per quelli usa stdio in locale. Per il deploy su server vedi Self-hosting.
Self-hosting
Un'istanza serve un solo account Fatture in Cloud con un solo bearer: per più clienti
avvia più istanze, ognuna con il suo .env, la sua porta e il suo token.
1. Installazione e configurazione (utente di sistema dedicato):
sudo useradd --system --create-home --home-dir /var/lib/fic-mcp fic-mcp
sudo -u fic-mcp pipx install git+https://github.com/nogarasimone/MCP-fattureincloud.git
sudo install -d -m 700 -o fic-mcp /etc/fic-mcp
sudo install -m 600 -o fic-mcp .env.example /etc/fic-mcp/.env # poi compila FIC_* e FIC_MCP_HTTP_TOKEN2. Token. fic-mcp auth apre il browser e attende il callback su localhost, quindi su un
server senza interfaccia grafica non funziona così com'è. Usa il token manuale, oppure esegui
fic-mcp auth sul tuo computer e copia tokens.json sul server
(FIC_TOKEN_FILE=/var/lib/fic-mcp/tokens.json, permessi 600). Il file deve restare scrivibile:
il server lo aggiorna quando rinnova l'access token.
3. Servizio systemd (/etc/systemd/system/fic-mcp.service):
[Unit]
Description=fic-mcp (MCP server Fatture in Cloud)
After=network-online.target
[Service]
User=fic-mcp
ExecStart=/var/lib/fic-mcp/.local/bin/fic-mcp --env-file /etc/fic-mcp/.env serve --transport http --host 127.0.0.1 --port 8000
Restart=on-failure
NoNewPrivileges=true
ProtectSystem=strict
ReadWritePaths=/var/lib/fic-mcp
[Install]
WantedBy=multi-user.targetsudo systemctl daemon-reload && sudo systemctl enable --now fic-mcpCon ProtectSystem=strict il registro scritture va messo in una cartella scrivibile, ad esempio
FIC_AUDIT_LOG=/var/lib/fic-mcp/audit.jsonl.
4. Reverse proxy con HTTPS. Il server ascolta solo su 127.0.0.1; all'esterno espone il proxy.
Per difesa dal DNS rebinding il server accetta solo l'header Host di localhost: dichiara il nome
pubblico nel .env, altrimenti le richieste dal proxy ricevono 421 Invalid Host header:
FIC_MCP_ALLOWED_HOSTS=mcp.tuodominio.it # più nomi separati da virgolaCaddy (certificato automatico):
mcp.tuodominio.it {
reverse_proxy 127.0.0.1:8000
}nginx (le risposte sono in streaming: niente buffering):
location /mcp {
proxy_pass http://127.0.0.1:8000;
proxy_http_version 1.1;
proxy_set_header Host $host;
proxy_buffering off;
proxy_read_timeout 300s;
}5. Verifica.
curl -i https://mcp.tuodominio.it/mcp # atteso: 401
curl -i -X POST https://mcp.tuodominio.it/mcp \
-H "Authorization: Bearer $FIC_MCP_HTTP_TOKEN" \
-H "Content-Type: application/json" -H "Accept: application/json, text/event-stream" \
-d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"curl","version":"0"}}}'La seconda chiamata deve rispondere 200. Con 421 Invalid Host header manca il nome pubblico in
FIC_MCP_ALLOWED_HOSTS; con 403 Invalid Origin header la richiesta arriva da un'origine web
diversa da https://<nome pubblico>.
Limiti da conoscere:
un solo processo: niente worker multipli né repliche dietro un bilanciatore. Con
FIC_PRIVACY_MODE=tokenizela tabella dei segnaposto vive in memoria e si azzera al riavvio;il bearer è l'unica protezione dell'endpoint: lungo (
openssl rand -hex 32), solo su HTTPS, da ruotare se esce dalla macchina; valuta anche una allowlist IP sul proxy;inizia con
FIC_READ_ONLY=trueanche sul server.
Configurazione
Variabile | Default | Significato |
| — | Token manuale o access token OAuth2 |
| — | Per |
| auto | Obbligatoria solo con più aziende |
|
|
|
|
|
|
|
|
|
|
| % dell'imponibile incassato da accantonare, oltre all'IVA |
|
| Registro scritture, |
| — | Bearer obbligatorio in modalità HTTP |
| — | Nomi pubblici ammessi nell'header |
fic-mcp tools mostra i tool che verrebbero esposti con la configurazione corrente
(R lettura, W scrittura, W! distruttiva o verso terzi).
Gruppi di tool
Gruppo | Default | Contenuto |
| ✓ | utente, aziende, selezione azienda, piano, stato server e quote |
| ✓ | clienti e fornitori: elenco con ricerca, dettaglio, crea, modifica, elimina |
| ✓ | prodotti/servizi e listini |
| ✓ | fatture, NC, preventivi, proforma, ordini, DDT, rapportini, autofatture: CRUD, totali, trasforma, unisci, email, allegati, cestino, fattura guidata, storico email |
| ✓ | verifica XML, scarica XML, invio SdI con dry run, motivo dello scarto |
| ✓ | spese, NC passive, DDT ricevuti, fatture SdI da registrare, allegati, cestino |
| ✓ | F24 e allegati |
| ✓ | prima nota |
| ✓ | aliquote IVA/nature, conti, metodi di pagamento, categorie, centri di costo, profilo fiscale, paesi, valute, unità di misura… (in cache) |
| ✓ | fatturato e incassi, crediti per anzianità, spese per categoria, stima IVA |
| corrispettivi | |
| archivio documenti | |
| conti, metodi di pagamento, aliquote IVA (CRUD), modelli | |
| sottoscrizioni webhook | |
|
|
Modello di sicurezza
Sola lettura (
FIC_READ_ONLY=true): i tool di scrittura non vengono nemmeno registrati. Il modo giusto per iniziare.Conferma esplicita: eliminazioni, invio allo SdI, email ai clienti, chiamate raw non-GET e modifiche alle impostazioni senza
confirm=truerestituiscono solo l'anteprima. Le istruzioni del server dicono al modello di chiedere il via libera all'utente prima di confermare.Invio SdI in due passi: senza conferma,
fic_send_e_invoiceesegue la verifica dell'XML e un invio di prova (dry_run) e mostra l'esito; l'invio reale parte solo conconfirm=true.Fattura guidata:
fic_create_invoicelavora condry_run=truedi default (calcola i totali con FIC e mostra l'anteprima senza creare nulla).Nessuna ripetizione di scritture ambigue: su timeout o errori di rete una POST/PUT non viene ripetuta; il messaggio dice di verificare in FIC prima di riprovare.
Registro scritture in JSONL (tool, ID, esito, orario): niente payload, quindi niente dati personali nel log.
Annotazioni MCP (
readOnlyHint,destructiveHint,idempotentHint) su ogni tool, così il client può chiedere conferma in base al rischio.Token salvati con permessi 600; i valori del filtro
qcostruiti dai tool vengono ripuliti dagli apici.
Privacy: tokenizzazione
Con FIC_PRIVACY_MODE=tokenize il modello riceve segnaposto stabili al posto di nomi e ragioni
sociali delle anagrafiche, P.IVA, codici fiscali, email, PEC, telefoni, indirizzi e IBAN, ad
esempio [[NOME_3]] o [[PIVA_1]]. Quando il modello riusa un segnaposto negli argomenti di un
tool, il server lo sostituisce con il valore reale prima di chiamare Fatture in Cloud: la ricerca
fic_list_clients(vat_number="[[PIVA_1]]") funziona. Un segnaposto sconosciuto genera un errore,
non una chiamata con dati inventati.
È pseudonimizzazione (art. 4(5) GDPR), non anonimizzazione. Limiti da dichiarare:
importi, date, numeri documento, città e descrizioni delle righe restano in chiaro;
nei testi liberi (descrizioni, note) si intercettano solo i pattern: email, IBAN, CF, P.IVA e cellulari. Un nome di persona scritto a mano in una descrizione passa;
la tabella di corrispondenza vive solo in memoria nel processo del server e si azzera al riavvio;
con la privacy attiva l'XML della fattura elettronica non viene restituito al modello (solo
save_tosu disco).
Analisi da CFO
fic_revenue_summary(year): competenza per mese (fatture meno note di credito: imponibile, rivalsa/cassa, IVA, ritenute) e cassa per mese (pagamenti segnati come pagati, anche su fatture dell'anno prima) con accantonamento = 100% dell'IVA incassata +FIC_SET_ASIDE_PCT% dell'imponibile incassato, e il disponibile che resta. In più: da incassare e primi 10 clienti.fic_receivables(): scadenzario crediti per fasce di ritardo (1–30, 31–60, 61–90, >90 giorni).fic_expenses_summary(year): spese per mese, categoria e fornitore; pagato e da pagare.fic_vat_estimate(dal, al): IVA vendite − IVA acquisti detraibile. Stima: non gestisce split payment, reverse charge, esigibilità differita né crediti precedenti.
I conteggi si fanno in Python sul server: il modello riceve totali, non migliaia di righe. Sono stime gestionali; i numeri fiscali li valida il commercialista.
Esempi di richieste
«Quanto ho fatturato e incassato nel 2026, mese per mese? Quanto devo tenere da parte?»
«Chi mi deve ancora pagare e da quanto?»
«Prepara la fattura di novembre per Rossi Consulting: 10 giornate a 500 €, IVA 22%, rivalsa INPS 4%, ritenuta 20%, scadenza 30 giorni.» → anteprima, poi creazione dopo il tuo OK.
«Ci sono fatture passive arrivate dallo SdI da registrare?»
«Verifica e invia allo SdI la fattura 555.» → controlli e dry run, poi invio dopo conferma.
Sviluppo e test
pip install -e ".[dev]"
pytestI test in tests/test_server.py girano end-to-end (client MCP in-process → server → finta API FIC): registrazione e
annotazioni dei tool, sola lettura, retry su 429, rinnovo del token su 401, errori 422 leggibili,
fattura guidata (rivalsa, ritenuta, scadenza, risoluzione aliquote), invio SdI in due passi,
conferme sulle eliminazioni, paginazione, analisi, tokenizzazione andata/ritorno, guardie del tool raw.
tests/test_cli.py copre i messaggi sugli errori di configurazione e il controllo dell'header
Host in modalità HTTP.
Struttura: client.py (HTTP, retry, quote, refresh), auth.py (OAuth2), privacy.py
(tokenizzazione), audit.py, registry.py (registrazione e filtri dei tool), tools/ (un modulo
per area), server.py, __main__.py (CLI).
Da verificare al primo collegamento reale
Il server è testato contro una simulazione dell'API costruita sulla documentazione ufficiale. Prima dell'uso in scrittura, in sola lettura:
fic-mcp doctorefic_whoami;filtri per cliente/fornitore (
entity.id = …nel parametroq): se FIC li rifiuta, l'errore lo dice e si usaqconentity.name;fic_create_invoicecondry_run=truesu un caso reale: confronta i totali con quelli che vedi in FIC;una prima fattura vera creata in bozza e controllata a video prima di
fic_send_e_invoice.
Segnalazioni e contributi
Bug e richieste: apri una issue usando i modelli proposti. Non incollare token, P.IVA, nomi di clienti o fatture reali: usa dati di esempio e oscura i log.
Vulnerabilità di sicurezza: non aprire una issue pubblica, segui SECURITY.md.
Pull request: benvenute; aggiungi un test in
tests/e verifica chepytestpassi.
Licenza
Rilasciato con licenza MIT. Progetto indipendente, non affiliato a Fatture in Cloud né a TeamSystem.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Fatture in Cloud MCP server for ChatGPT, Claude and any AI agent: create invoice, send to SDI, add client, record expense and list unpaid invoices in your own Fatture in Cloud account. Cotlet works in the account through your Cloud Browser, a real Chrome where you sign in to Fatture in Cloud yourself; Cotlet does not store your password and you need no Fatture in Cloud API key. About the official Fatture in Cloud API: Yes, Fatture in Cloud has a documented REST API (v2) for issued invoices, clients, received documents, e-invoices to SDI and attachments (checked 14 Oct 2026), but it has no official MCP server. To use it you register an OAuth 2.0 app, or create a manual access token in the web app, choose scopes and pick the companies the token applies to. Setup and FAQ: https://cotlet.dev/integrations/fatture-in-cloud-api-mcp-server
Read invoices, clients, suppliers and cashbook; create invoices and clients in Fatture in Cloud.
Invoicing, expenses, accounting analytics. OAuth 2.1 dynamic client registration, no API key.
OAuth MCP for text, jobs, quotes, and receipts. No image/video/audio/3D generation.
Related MCP Servers
- AlicenseAqualityCmaintenanceMCP server for the Fatture in Cloud API v2 that lets Claude read and manage issued and received documents (invoices, credit notes, quotes, expenses, etc.) via CRUD operations.14118 npm1MIT
- AlicenseNot gradedqualityDmaintenanceEnables MCP-compatible agents to securely access an Invoice4U account for searching documents and customers and creating receipts linked to paid invoices, with read-only behavior by default.1MIT
- AlicenseAqualityBmaintenanceEnables Claude to access, analyze, and optionally modify invoices, installments, receipts, clients, and financial reports via the Fatture in Cloud API v2, with read-only default and multi-layer safety.171MIT
- AlicenseBqualityCmaintenanceEnables MCP clients such as Claude Desktop to read and, after per-transaction confirmation, write accounting data—invoices, customers, items, payments, deposits, checks/bank charges, and journal entries—with two-step confirmation and revert of its own runs.25MIT