# Fattureincloud Mcp Server

> MCP Server per Fatture in Cloud — 20 tools con netting NC, aging report, analytics e workflow solleciti

- **Type:** MCP server
- **Install:** `agentstack add mcp-maxmost-hestro-fattureincloud-mcp-server`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [maxmost-hestro](https://agentstack.voostack.com/s/maxmost-hestro)
- **Installs:** 0
- **Category:** [Data & Analytics](https://agentstack.voostack.com/c/data-and-analytics)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [maxmost-hestro](https://github.com/maxmost-hestro)
- **Source:** https://github.com/maxmost-hestro/fattureincloud-mcp-server

## Install

```sh
agentstack add mcp-maxmost-hestro-fattureincloud-mcp-server
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# FattureInCloud MCP Server

[](LICENSE)
[](https://www.python.org/downloads/)

Un server [Model Context Protocol](https://modelcontextprotocol.io/) (MCP) completo che collega assistenti AI come Claude alla piattaforma di fatturazione [Fatture in Cloud](https://www.fattureincloud.it/).

**28 tools** organizzati in 10 categorie che vanno ben oltre il semplice wrapping delle API: paginazione automatica, netting delle note di credito, analisi aging, scoring comportamento pagamenti, dati strutturati per i workflow di sollecito, lettura del catalogo articoli / magazzino per la valorizzazione delle rimanenze, scrittura magazzino protetta da guardrail (carico/scarico/categoria/anagrafica) e lettura dedicata dei preventivi.

---

## Perche' questo progetto

Le API di Fatture in Cloud sono potenti ma di basso livello: interroghi un tipo di documento alla volta, pagini manualmente e ottieni dati grezzi che richiedono post-elaborazione per qualsiasi insight di business reale.

Questo MCP server si interpone tra il tuo assistente AI e le API, aggiungendo un **layer di logica di business** che trasforma i dati contabili grezzi in informazioni operative — il tutto accessibile tramite linguaggio naturale.

### Cosa ottieni rispetto alle API standard

| Funzionalita' | API FIC | Questo MCP Server |
|---|---|---|
| Lista fatture | Un tipo di documento per chiamata, paginazione manuale | Tutti i tipi di documento in una chiamata, paginazione automatica su tutte le pagine |
| Stato pagamento | Array `payments_list` grezzo | Stato calcolato (pagata/parziale/non pagata), importo residuo, estrazione scadenza con logica di fallback |
| Gestione note di credito | Query separate, riconciliazione manuale | **Netting FIFO automatico** — le NC vengono abbinate alle fatture per cliente, dalla piu' vecchia |
| Fatture scadute | Nessun concetto nativo | Rilevamento intelligente con calcolo giorni di ritardo, raggruppate per gravita' |
| Aging report | Non disponibile | Fasce standard (1-30, 31-60, 61-90, 90+ giorni) con netting NC automatico |
| Analytics fatturato | Non disponibile | Mensile, trimestrale, annuale, per cliente — tutto pre-aggregato |
| Analytics spese | Non disponibile | Aggregazione mensile spese con filtro fornitore |
| Comportamento pagamenti cliente | Non disponibile | Calcolo DSO, % ritardi, trend anno su anno, rating affidabilita' |
| Priorita' solleciti | Non disponibile | Coda priorita' pesata: `importo * log(giorni) * sqrt(fatture)` |
| Dati per solleciti | Non disponibile | Output strutturato con contatti cliente + fatture scadute, pronto per generare email |

---

## Architettura

```
fattureincloud-mcp-server/
├── server.py              # Entry point — registra tutti i tools, supporta stdio + SSE + streamable-http
├── auth_setup.py          # Wizard interattivo per setup OAuth2
├── src/
│   ├── config.py          # Configurazione API (token OAuth2, company ID)
│   ├── utils.py           # Utility condivise (estrazione stato pagamento)
│   └── tools/
│       ├── invoices.py    # Documenti emessi (2 tools)
│       ├── payments.py    # Pagamenti e scadenze (2 tools)
│       ├── clients.py     # Gestione clienti (2 tools)
│       ├── expenses.py    # Documenti ricevuti e spese (5 tools)
│       ├── analytics.py   # Statistiche e report fatturato (3 tools)
│       ├── info.py        # Informazioni azienda (1 tool)
│       ├── reminders.py   # Solleciti e analisi crediti (5 tools)
│       ├── products.py    # Catalogo articoli / magazzino (2 tools, read-only)
│       ├── products_write.py # Scrittura magazzino (5 tools, guarded)
│       └── quotes.py      # Preventivi emessi (1 tool, read-only)
├── Dockerfile             # Container per deploy remoto
└── requirements.txt       # Dipendenze Python
```

### Modalita' di trasporto

| Modalita' | Caso d'uso | Comando |
|---|---|---|
| **stdio** (default) | Claude Code, Claude Desktop | `python server.py` |
| **streamable-http** | claude.ai, deploy remoto (MCP 2025-03-26) | `python server.py --transport streamable-http --port 3002` |
| **sse** | Legacy HTTP/SSE | `python server.py --transport sse --port 3002` |

---

## Riferimento Tools (20 totali)

### Fatture emesse (2 tools)

| Tool | Descrizione |
|---|---|
| `get_invoices` | Lista documenti emessi con filtri (intervallo date, nome cliente, stato pagamento). Interroga tutti i tipi di documento (fatture, note di credito, ricevute, ecc.) con paginazione automatica. |
| `get_invoice` | Dettaglio completo di una singola fattura: righe, piano pagamenti, stato e-invoice, allegati. |

### Pagamenti (2 tools)

| Tool | Descrizione |
|---|---|
| `get_overdue_invoices` | Tutte le fatture scadute non pagate, ordinate per giorni di ritardo. Scansiona fino a 5 anni di storico. |
| `get_payment_summary` | Dashboard pagamenti aggregata: totale fatturato, incassato, da incassare, numero e importo scaduti, con percentuali. |

### Clienti (2 tools)

| Tool | Descrizione |
|---|---|
| `get_clients` | Anagrafica clienti completa: dati fiscali, indirizzi, contatti, PEC, codice SDI, condizioni di pagamento predefinite. |
| `get_client_invoices` | Tutte le fatture per un cliente specifico con riepilogo pagamenti. |

### Spese (5 tools)

| Tool | Descrizione |
|---|---|
| `get_received_invoices` | Fatture ricevute da fornitori con paginazione intelligente (mese per mese per intervalli lunghi). |
| `get_received_credit_notes` | Note di credito ricevute dai fornitori (`passive_credit_note`), con la stessa paginazione intelligente. Include sempre descrizione completa e righe di dettaglio per il matching con le fatture originali (es. esclusione di cespiti stornati da resi/errori). |
| `get_received_invoice` | Dettaglio completo di una fattura ricevuta: righe, deducibilita', piano pagamenti. |
| `get_unpaid_received_invoices` | Fatture passive non ancora pagate — la tua dashboard debiti verso fornitori. |
| `get_expenses_by_month` | Aggregazione spese mensili per qualsiasi anno, con totali e medie. |

### Analytics (3 tools)

| Tool | Descrizione |
|---|---|
| `get_revenue_by_month` | Fatturato mensile per qualsiasi anno. |
| `get_revenue_by_client` | Fatturato per cliente (top N) con percentuali — la tua analisi di Pareto. |
| `get_yearly_stats` | Dashboard annuale completa: fatturato, clienti attivi, cliente top, medie, dettaglio trimestrale. |

### Info azienda (1 tool)

| Tool | Descrizione |
|---|---|
| `get_company_info` | Informazioni sulle aziende associate all'account. |

### Solleciti e analisi crediti (5 tools)

Qui sta il vero valore aggiunto. Questi tools implementano logica di business che non esiste nelle API FIC:

| Tool | Descrizione |
|---|---|
| `get_overdue_invoices_with_netting` | Fatture scadute con **netting FIFO automatico delle note di credito**. Raggruppa fatture e NC per cliente, applica i crediti alle fatture piu' vecchie, mostra fatture coperte totalmente o parzialmente. |
| `get_aging_report` | Analisi aging standard con 4 fasce (1-30, 31-60, 61-90, 90+ giorni). Include netting NC. Mostra il dettaglio delle posizioni critiche. |
| `get_reminder_data` | Dati strutturati per generare lettere di sollecito: anagrafica completa del cliente (nome, PEC, email, telefono, indirizzo) + tutte le fatture scadute con importi e giorni di ritardo. |
| `get_client_payment_behavior` | Analisi affidabilita' pagamenti su 3 anni: DSO (Days Sales Outstanding), % pagamenti in ritardo, trend anno su anno (migliora/peggiora/stabile) e rating da 1 a 5 stelle. |
| `get_reminder_priority_queue` | Lista prioritizzata dei clienti da sollecitare, con score: `importo * log(giorni_ritardo) * sqrt(num_fatture)`. Include livello urgenza (critico/alto/medio/basso) e contatti. |

### Catalogo articoli / magazzino (2 tools, read-only)

Lettura del catalogo articoli per la valorizzazione delle rimanenze di magazzino. Nessuna scrittura su FIC.

| Tool | Descrizione |
|---|---|
| `get_products` | Catalogo articoli con categoria, unita' di misura, costo unitario (`net_cost`/`average_cost`), giacenza (`stock_initial`/`stock_current`), prezzo e note. Filtri opzionali: `category`, `search`, `in_stock_only`, `limit`. In testa un riepilogo per categoria con valore giacenza = `sum(stock_current * net_cost)`. |
| `get_product_categories` | Elenco delle categorie magazzino (tassonomia ufficiale FIC, `context="products"`) arricchito con conteggio articoli e valore giacenza per categoria. |

### Scrittura magazzino (5 tools, guarded)

Operazioni di SCRITTURA sugli articoli (carico/scarico, categoria, anagrafica, create/delete), pensate per lo step carico/scarico di `prep-bilancio`. FIC non ha movimenti di magazzino giornalizzati: carico/scarico/rettifica sono realizzati come read-modify-write della giacenza.

**Doppia barriera di sicurezza:**
1. Env flag globale **`FIC_ALLOW_WRITE`** (default off): se diverso da `true`, ogni scrittura e' rifiutata. Va aggiunto (`-e FIC_ALLOW_WRITE=true`) SOLO ai profili che devono scrivere.
2. Parametro **`confirm`** per ogni tool: senza `confirm=true` il tool esegue un **dry-run** con anteprima `prima -> dopo`, senza scrivere.

Scarico bloccato sotto zero, ogni scrittura loggata, una scrittura per chiamata (nessun batch).

| Tool | Descrizione |
|---|---|
| `product_update_stock` | Carico / scarico / rettifica giacenza (`operation`: `set`/`carico`/`scarico`). |
| `product_update_category` | Cambia la categoria di un articolo. |
| `product_update_fields` | Modifica `net_cost`, `net_price`, `name`, `code`, `measure`, `notes`. |
| `product_create` | Crea un nuovo articolo. |
| `product_delete` | Cancella un articolo (FIC rifiuta se usato in documenti). |

> Nota (2026-06-01): la scrittura non e' ancora abilitabile in produzione. Il token OAuth corrente e' read-only e FIC risponde `403 NO_PERMISSION`. Per abilitarla servono lo scope `products:a` in `auth_setup.py` e una ri-autorizzazione del token. Il campo giacenza usato (`stock_initial`) andra' poi confermato con un test su articolo non critico.

### Preventivi (1 tool, read-only)

| Tool | Descrizione |
|---|---|
| `get_quotes` | Elenco preventivi emessi (`type="quote"`): numero, data, cliente, oggetto, validita' (`next_due_date`), data "visto" (`seen_date`), importi e link PDF. Filtri: `from_date`, `to_date`, `client_name`, `limit`. Tool dedicato perche' `get_invoices` mescola i preventivi con gli altri documenti emessi. |

### Netting Note di Credito — Come funziona

L'algoritmo `_apply_netting_fifo`:

1. Raggruppa note di credito e fatture per nome cliente (case-insensitive)
2. Ordina le fatture per data di emissione (piu' vecchie prima — FIFO)
3. Somma tutte le NC per cliente (usando `amount_net`)
4. Applica i crediti in sequenza:
   - Se credito >= importo fattura → fattura completamente coperta (esclusa dallo scaduto)
   - Se credito < importo fattura → riduce il saldo residuo
5. Tolleranza di 0.01 EUR per arrotondamenti floating-point

---

## Quick Start

### 1. Prerequisiti

- Python 3.11+
- Un account [Fatture in Cloud](https://www.fattureincloud.it/)
- Un'app OAuth2 registrata su [developers.fattureincloud.it](https://developers.fattureincloud.it)

### 2. Installazione

```bash
git clone https://github.com/maxmost-hestro/fattureincloud-mcp-server.git
cd fattureincloud-mcp-server

python -m venv venv
source venv/bin/activate   # macOS/Linux
# venv\Scripts\activate    # Windows

pip install -r requirements.txt
```

### 3. Configurazione

#### Opzione A: Setup interattivo (consigliato)

```bash
python auth_setup.py
```

Lo script:
- Apre il browser per l'autorizzazione OAuth2
- Scambia il codice per access/refresh token
- Rileva automaticamente il tuo company ID
- Salva tutto nel file `.env`

#### Opzione B: `.env` manuale

```bash
cp .env.example .env
# Modifica .env con le tue credenziali
```

### 4. Avvio

```bash
# Modalita' stdio (per Claude Code / Claude Desktop)
python server.py

# Streamable HTTP — richiesto da claude.ai (MCP spec 2025-03-26)
python server.py --transport streamable-http --host 0.0.0.0 --port 3002

# Legacy HTTP/SSE
python server.py --transport sse --host 0.0.0.0 --port 3002
```

### 5. Collegamento a Claude Code

Aggiungi al tuo `~/.claude.json` o alle impostazioni di Claude Code:

```json
{
  "mcpServers": {
    "fattureincloud": {
      "command": "python",
      "args": ["/path/to/fattureincloud-mcp-server/server.py"]
    }
  }
}
```

Poi chiedi a Claude cose come:
- *"Mostrami le fatture scadute"*
- *"Qual e' il fatturato 2025 per cliente?"*
- *"Chi devo sollecitare con priorita'?"*
- *"Analizza il comportamento di pagamento di ACME Srl"*
- *"Quanto abbiamo speso questo mese?"*
- *"Dammi l'aging report"*

---

## Variabili d'Ambiente

| Variabile | Descrizione | Obbligatoria |
|---|---|---|
| `FIC_ACCESS_TOKEN` | Token di accesso OAuth2 | Si |
| `FIC_COMPANY_ID` | ID azienda in Fatture in Cloud | Si |
| `FIC_COMPANY_NAME` | Nome azienda (solo visualizzazione) | No |
| `FIC_CLIENT_ID` | Client ID dell'app OAuth2 | Per `auth_setup.py` |
| `FIC_CLIENT_SECRET` | Client Secret dell'app OAuth2 | Per `auth_setup.py` |

### Scope OAuth2 richiesti

```
issued_documents:r    # Lettura fatture emesse
received_documents:r  # Lettura fatture ricevute
entities:r            # Lettura clienti/fornitori
settings:r            # Lettura impostazioni
situation:r           # Lettura situazione contabile
```

---

## Deploy con Docker

```bash
# Build
docker build -t fattureincloud-mcp .

# Run con streamable HTTP (default, per claude.ai)
docker run -d \
  --name fattureincloud-mcp \
  -p 3002:3002 \
  --env-file .env \
  fattureincloud-mcp

# Run con stdio (per Claude Code locale)
docker run -i --rm --env-file .env fattureincloud-mcp python server.py
```

---

## Workflow Solleciti

Il flusso consigliato per gestire i pagamenti scaduti:

```
1. get_overdue_invoices_with_netting
   → Lista pulita fatture scadute (note di credito gia' applicate)

2. get_aging_report
   → Situazione per fascia temporale (1-30, 31-60, 61-90, 90+ giorni)

3. get_reminder_priority_queue
   → Chi contattare per primo, ordinato per score di urgenza

4. get_reminder_data (per cliente)
   → Contatti + dettaglio fatture per la mail di sollecito

5. get_client_payment_behavior (opzionale)
   → DSO, trend e rating per calibrare il tono del sollecito
```

---

## Stack Tecnologico

| Componente | Versione | Scopo |
|---|---|---|
| Python | 3.11+ | Runtime |
| `fattureincloud-python-sdk` | 2.1.3 | Client ufficiale API FIC |
| `mcp` | latest | MCP SDK di Anthropic |
| `python-dotenv` | 1.0.1 | Configurazione da ambiente |
| `uvicorn` | 0.27+ | Server ASGI (modalita' HTTP/SSE) |
| `starlette` | 0.36+ | Web framework (modalita' HTTP/SSE) |

---

## Come Contribuire

Vedi [CONTRIBUTING.md](CONTRIBUTING.md) per le linee guida.

---

## Changelog

Vedi [CHANGELOG.md](CHANGELOG.md) per la storia delle modifiche.

---

## Licenza

Questo progetto e' distribuito sotto licenza MIT. Vedi [LICENSE](LICENSE) per i dettagli.

---

**Autore:** Massimo Mostallino — [massimo.mostallino@hestro.it](mailto:massimo.mostallino@hestro.it) — [hestro.it](https://www.hestro.it)

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [maxmost-hestro](https://github.com/maxmost-hestro)
- **Source:** [maxmost-hestro/fattureincloud-mcp-server](https://github.com/maxmost-hestro/fattureincloud-mcp-server)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** yes
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-maxmost-hestro-fattureincloud-mcp-server
- Seller: https://agentstack.voostack.com/s/maxmost-hestro
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.