Fattura24 MCP Bridge · ChatGPT + Claude + Docker

Progetto open source non ufficiale, indipendente da Fattura24, OpenAI e Anthropic. La modalità predefinita è sola anteprima. Include adesso anche una prima integrazione di scrittura reale per fatture semplici tramite API ufficiali, disattivata finché l'utente non abilita esplicitamente le operazioni. DDT, invio SdI, automazione di Docker da ChatGPT e accesso remoto non sono completati.

🎯 A cosa serve?

Vuoi chiedere a un assistente AI: «Preparami una fattura per 10 unità a 25 euro + IVA», controllare i totali e ottenere un'anteprima senza aprire decine di schermate. Questo repository contiene un piccolo server MCP avviabile con Docker Desktop su Windows o Mac, istruzioni per ChatGPT e una skill per Claude.

Attenzione: la funzionalità di analisi dei dati contabili è già disponibile tramite il server MCP ufficiale Fattura24, separato dal bridge. Il server ufficiale è prevalentemente di sola lettura. Il bridge supporta anche il salvataggio REST opzionale di fatture semplici quando configurato e attivato; resta necessario il controllo dei documenti nell'interfaccia ufficiale.

Cosa funziona

Related MCP server: Italy Invoice MCP

🧩 Come sono collegati i componenti

flowchart TD
    U["Utente: Windows / Mac / Smartphone"] --> AI["ChatGPT o Claude"]
    AI --> O["MCP ufficiale Fattura24\nlettura e report"]
    AI -. "solo con URL HTTPS autenticato e configurato" .-> B["Bridge MCP Docker\nanteprime soltanto"]
    B --> D["Docker Desktop\nPC acceso"]
    O --> F["Fattura24"]
    B -. "SaveDocument opzionale, solo fatture semplici" .-> F

✅ Requisiti

Windows: Windows 11, Docker Desktop con WSL2 attivo, PowerShell e connessione Internet per scaricare l'immagine base. Mac: macOS compatibile, Docker Desktop per chip Intel o Apple Silicon, Terminale. Non serve una chiave API OpenAI, né un VPS. Il piano Fattura24 può limitare la disponibilità delle sue API.

Docker Desktop deve essere installato prima di avviare il progetto. Se non c'è, lo script si ferma; non installa software senza consenso.

🚀 Avvio in 3 passaggi

Windows 11

1. Installa Docker Desktop e avvialo la prima volta.

2. Scarica il repository come ZIP (pulsante Code → Download ZIP) e apri PowerShell nella cartella estratta.

3. Esegui:

powershell -ExecutionPolicy Bypass -File .\scripts\start.ps1
curl.exe http://127.0.0.1:8765/health

Se vedi ok il container risponde. Lo script crea un token locale nel file .env, che non deve essere pubblicato. Arresta con powershell -File .\scripts\stop.ps1.

macOS (Intel e Apple Silicon)

1. Installa Docker Desktop per Mac per il processore corretto.

2. Apri Terminale nella cartella scaricata.

3. Esegui:

bash ./scripts/start-mac.sh
curl -fsS http://127.0.0.1:8765/health

Arresta con bash ./scripts/stop-mac.sh.

Senza script (Windows, Mac, Linux con Docker già avviato)

Crea .env copiando .env.example e sostituisci il valore BRIDGE_TOKEN con una stringa casuale lunga; poi:

docker compose up -d --build
docker compose ps
docker compose logs --tail=50

Usa solo dati fittizi durante i test. Docker pubblica il servizio esclusivamente su 127.0.0.1:8765.

🧾 Salvataggio reale di fatture (funzione sperimentale, disattivata per sicurezza)

Novità: il Docker include fattura24_client.py, che utilizza l'endpoint ufficiale POST /api/v0.3/SaveDocument per fatture semplici di tipo I (analogica) oppure FE (elettronica). Il salvataggio crea il documento nell'account Fattura24, non lo invia allo SdI. Fatture con ritenute, casse, reverse charge, altri regimi speciali e casistiche complesse richiedono verifiche e possono non essere gestite da queste API. I DDT non sono ancora registrabili automaticamente dal bridge. Documentazione: creare documento e fattura elettronica.

Prima di attivarlo: leggi il regolamento API Fattura24 che richiede un ambiente di test e controllo manuale. Crea prima documenti di prova sul tuo account e verifica gli esiti. Non effettuare test di scrittura con documenti che non vuoi registrare.

Configurazione: apri il file locale .env (creato dallo script di avvio). Aggiungi:

FATTURA24_API_KEY=LA_TUA_CHIAVE_FATTURA24
FATTURA24_ENABLE_WRITES=true

La chiave si genera in Fattura24 → Configurazione → App e servizi esterni → API, se prevista dal tuo piano. Non confonderla con le API OpenAI. Non metterla su GitHub, in ChatGPT o nella skill. Ricarica il container con docker compose up -d --force-recreate.

La chiamata save_invoice_to_fattura24 è accessibile solo via MCP protetto dal token locale; richiede l'anteprima del documento, una conferma esplicita dell'utente, la stringa CONFERMO IL SALVATAGGIO IN FATTURA24 e un request_id unico per quel tentativo. Lo stesso identificatore non genera una seconda fattura. In caso di timeout/errore ambiguo l'operazione resta marcata uncertain: non riprovare automaticamente; controlla Fattura24 per evitare duplicati. Lo storico tecnico anti-duplicati è conservato nel volume Docker fattura24_state. Non eliminare quel volume quando riavvii.

Lo strumento invoice_api_payload_preview restituisce il vero payload XML SaveDocument (non XML FatturaPA) che l'API riceverebbe. invoice_xml_preview, invece, resta l'esempio generico e non deve essere inviato all'API.

Limiti attuali: nessuna automazione SdI, nessun PDF generato dal bridge, nessun browser gestito per DDT. La guida Fattura24 prevede che l'invio delle fatture elettroniche allo SdI avvenga dall'interfaccia Fattura24. Questa implementazione non è stata collaudata con credenziali reali; gli strumenti sono sottoposti a test unitari e ai controlli GitHub Actions, non a una certificazione fiscale.

🔬 Collaudo automatico sul tuo computer (senza creare fatture)

Questo è il primo test pratico da eseguire dopo l'avvio con start.ps1 (Windows) oppure start-mac.sh (Mac). Verifica che l'immagine Docker non si limiti ad avviarsi, ma risponda davvero attraverso il protocollo MCP.

Windows — PowerShell:

python .\scripts\smoke_test.py

Mac — Terminale:

python3 ./scripts/smoke_test.py

Per questo test occorre Python sul computer (non serve per far girare il servizio Docker). Se preferisci evitare Python locale, consulta il job mcp-integration in GitHub → Actions → Tests: GitHub esegue automaticamente lo stesso test in un container, senza chiavi Fattura24.

Il test interroga /health, verifica che il server rifiuti richieste MCP senza token, inizializza una sessione MCP, legge l'elenco degli strumenti e invoca prepare_invoice con dati inventati. Non usa chiavi API né invia richieste a Fattura24. Il risultato atteso è TUTTI I CONTROLLI SUPERATI.

In caso di errore, copia solo il messaggio finale senza token e verifica:

docker compose ps
docker compose logs --tail=100

Il collaudo sul tuo PC non può essere eseguito dal cloud ChatGPT. Gli script devono essere avviati sul sistema dove è installato Docker Desktop. Un test GitHub Actions riuscito conferma l'ambiente CI Linux, non Windows/macOS.

🧪 Verificare che funzioni

curl http://127.0.0.1:8765/health

Per usare gli strumenti MCP bridge_status, prepare_invoice, invoice_xml_preview e prepare_ddt_notes, occorre un client MCP locale che supporti Streamable HTTP e l'header Authorization: Bearer <BRIDGE_TOKEN>. L'URL MCP è http://127.0.0.1:8765/mcp. Non incollare il token in ChatGPT o nei ticket pubblici.

Esempio di dati JSON fittizi per una bozza:

{
  "document_type": "FE",
  "customer_name": "Cliente di prova",
  "rows": [{
    "description": "Prodotto dimostrativo",
    "quantity": "10",
    "price_net": "25.00",
    "vat_code": "22",
    "vat_description": "22%"
  }]
}

Imponibile dimostrativo €250,00; IVA €55,00; totale €305,00 (esempio aritmetico, non controllo fiscale).

Test automatici

python -m pip install -r requirements-dev.txt
python -m pytest -q

Oppure usa GitHub Actions (workflow incluso) dopo il primo commit.

🤖 ChatGPT e Claude

• ChatGPT: la configurazione installabile del connettore ufficiale è in chatgpt-plugin/. Il bridge locale non è raggiungibile dal cloud con localhost: la connessione da ChatGPT richiede un URL HTTPS pubblico o una soluzione di accesso supportata, autenticazione appropriata e ulteriori verifiche. Il plugin privato precedentemente creato è Fattura24 AI Assistant, non automaticamente collegato a questo container.

• Claude: istruzioni in .claude/skills/fattura24/SKILL.md, utilizzabili come guida; l'effettiva disponibilità degli strumenti MCP dipende dal client e dalla sua configurazione.

• Skill portabile: skills/fattura24/SKILL.md.

Non aprire la porta 8765 sul router. GitHub pubblico pubblica codice, non pubblica automaticamente un server. Una VPN da sola non assicura che un client AI cloud possa raggiungere un endpoint privato.

📂 Struttura dei file

.
├── Dockerfile                 # Immagine Python multipiattaforma
├── compose.yaml               # Porta accessibile solo dal PC
├── server.py                  # MCP con protezione Bearer
├── core.py                    # Modelli e calcoli anteprima
├── fattura24_client.py        # SaveDocument API opt-in, senza ritentativi automatici
├── scripts/start.ps1          # Windows: controlla/apre Docker
├── scripts/start-mac.sh       # Mac: controlla/apre Docker
├── chatgpt-plugin/            # Plugin portabile, MCP ufficiale
├── .claude/skills/fattura24/  # Skill Claude
├── skills/fattura24/          # Skill condivisa
├── docs/images/               # Diagrammi SVG originali
├── tests/                     # Test automatici
├── SECURITY.md                # Sicurezza
└── LICENSE                    # MIT

🔐 Sicurezza

• La chiave API Fattura24 non è necessaria per la funzione di sola anteprima e non deve comparire nel repository.

• Non usare credenziali o dati personali reali negli esempi o nei commit.

• In caso di timeout durante una futura creazione di fatture, non ritentare alla cieca: rischio duplicazione/numerazione.

• Qualsiasi futura scrittura richiederà un pannello locale di approvazione, test isolati e verifica manuale. Nessuna promessa di invio automatico SdI.

• Leggi SECURITY.md e le condizioni ufficiali prima di integrare le API.

📚 Fonti ufficiali e normative tecniche

Le fonti seguenti sono documentazione del fornitore, non una certificazione di questo progetto.

1. Fattura24 — Perché MCP

2. Fattura24 — Tool MCP disponibili

3. Fattura24 — Riferimento tecnico MCP

4. Fattura24 — Creare un documento via API REST

5. Fattura24 — Regolamento API — limiti, sicurezza, test, niente chiamate concorrenti e invio SdI manuale.

6. Model Context Protocol

7. Docker Desktop

8. OpenAI — Apps SDK / MCP

9. Anthropic — Claude Code Skills

⚖️ Licenza e marchi

Codice e diagrammi originali sotto licenza MIT. Il nome Fattura24 è un marchio del relativo titolare. L'uso del nome serve a identificare il servizio interoperabile; non implica partnership o approvazione.

📇 Rubrica clienti, verifica API e PDF — estensioni

Il Docker include tre ulteriori operazioni basate su API documentate:

• verify_fattura24_api_key: chiama TestKey soltanto su richiesta esplicita, mai come sonda di disponibilità.

• customer_payload_preview e save_customer_to_fattura24: crea oppure aggiorna una scheda cliente tramite SaveCustomer; richiede FATTURA24_ENABLE_WRITES=true, request_id unico e la frase CONFERMO CREAZIONE O AGGIORNAMENTO CLIENTE dopo l'anteprima. Fattura24 può aggiornare un cliente già esistente, quindi non è una prova innocua.

• download_document_pdf: scarica il PDF già creato, tramite GetFile e docId. Per ragioni di riservatezza, il risultato contiene il documento codificato base64; non mostrarlo per intero in chat e non inserirlo nei log.

Fonti: TestKey, SaveCustomer, GetFile.

Limiti espliciti: la generazione di PDF di DDT o la compilazione del gestionale tramite un browser automatizzato non sono ancora presenti. Anche una futura automazione browser richiederà una sessione autenticata sul dispositivo sotto controllo dell'utente e test sulla UI reale. Non esiste un metodo per attivare un server Docker spento da un plugin cloud senza un agente locale o un sistema remoto già operativo.