MCP Invoice

Facturas numeradas con líneas de impuestos, renderizadas a un PDF profesional.

Documentación

mcp-invoice

Di "crea una fattura per Acme, 12 ore a 90 EUR, scadenza tra 14 giorni" e ottieni un vero PDF da inviare. Questo server MCP memorizza il tuo profilo aziendale e i tuoi clienti, assegna un numero di fattura sequenziale che non viene mai riutilizzato, calcola il subtotale, eventuali sconti, una riga di imposta per ogni aliquota IVA e il totale in unità minori intere, e genera un PDF A4 con i tuoi dati di emittente e pagamento, una tabella di voci che va a capo e un blocco totali corretto. Tiene anche traccia dei pagamenti e, nella versione Pro, segnala cosa è scaduto e di quanti giorni. Tutto è archiviato in semplici file JSON sul tuo computer; nulla viene caricato da nessuna parte.

invoice demo

Crea fatture numerate con righe di imposta e un vero PDF dalla chat, senza bisogno di un SaaS di fatturazione.

Installazione in 60 secondi

La pubblicazione npm per @theluckystrike/mcp-invoice è in sospeso. Fino ad allora, il bundle con un clic .mcpb o un clone+compilazione è il percorso funzionante: entrambi sono verificati di seguito.

Con un clic (.mcpb): scarica invoice.mcpb dall'ultima release e fai doppio clic su di esso in Claude Desktop: https://github.com/theluckystrike/mcp-servers/releases/latest

Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "invoice": {
      "command": "npx",
      "args": ["-y", "@theluckystrike/mcp-invoice"]
    }
  }
}

Claude Code:

claude mcp add invoice -- npx -y @theluckystrike/mcp-invoice

Cursor (.cursor/mcp.json):

{
  "mcpServers": {
    "invoice": {
      "command": "npx",
      "args": ["-y", "@theluckystrike/mcp-invoice"]
    }
  }
}

Il modulo npx sopra inizia a funzionare nel momento in cui il pacchetto viene pubblicato. Fino ad allora, usa il bundle .mcpb sopra, oppure compila dal sorgente con esattamente questi tre comandi:

git clone https://github.com/theluckystrike/mcp-servers.git && cd mcp-servers
npm install
npm run build -w packages/mcp-license -w servers/invoice

Poi punta il command del tuo client a node con un argomento: il percorso assoluto di servers/invoice/dist/index.js.

Per eseguire in modalità Pro, imposta MCP_LICENSE_KEY nello stesso blocco di configurazione, oppure chiama license_activate una volta con la tua chiave.

Strumenti

Strumento	Cosa fa
`business_set`	Memorizza il profilo dell'emittente: nome, indirizzo, email, partita IVA, IBAN, banca, logo, valuta predefinita, aliquota fiscale predefinita, termini di pagamento, prefisso fattura. `tax_rate`, `vat_rate` e `vat` sono accettati come alias per `default_tax_rate`, e qualsiasi campo non riconosciuto viene segnalato invece di essere scartato
`client_add`	Aggiungi o aggiorna un cliente (nome, indirizzo, email, partita IVA)
`client_list`	Elenca i clienti memorizzati con i loro ID
`invoice_create`	Crea una fattura da voci; assegna il numero successivo, calcola lo sconto, l'imposta per aliquota e il totale. Le voci possono avere un `currency` per riga, e una combinazione viene rifiutata piuttosto che fatturata come un'unica valuta. Se il cliente viene creato da un semplice nome, la risposta indica che il blocco BILL TO non ha indirizzo e come aggiungerlo
`invoice_from_hours`	Scorciatoia: fattura un cliente per N ore a una tariffa oraria. `target_currency` + `fx_rates` emettono la fattura in un'altra valuta (fornisci tu il tasso); `entry_ids` restituiscono il nuovo numero di fattura così le ore tracciate possono essere chiuse con il `entry_mark_billed` del tracker del tempo
`invoice_list`	Elenca le fatture, filtrate per stato, cliente e intervallo di date di emissione
`invoice_get`	Record completo memorizzato per un numero di fattura
`invoice_mark_paid`	Registra un pagamento totale o parziale; riporta il saldo dovuto
`invoice_pdf`	Genera il PDF A4 e restituisce il percorso del file. La risposta chiama il file PDF solo quando lo è davvero
`overdue_report`	Fatture non pagate scadute, giorni di ritardo, totali dovuti per valuta. Gratuito
`license_status`	Mostra la modalità gratuita o Pro
`license_activate`	Attiva una chiave Pro (verificata offline)

Risorsa: invoices://open restituisce ogni fattura non pagata o parzialmente pagata come JSON.

Prompt: monthly_invoicing esamina cosa è non pagato e cosa è scaduto per un mese, poi abbozza la fattura successiva.

Cosa puoi dire

Tu dici	Strumento
"Configura la mia attività: Acme Consulting, EUR, IVA 23%, termini 14 giorni."	`business_set`
"Aggiungi un cliente: Beta Corp, la loro partita IVA è..., email billing@beta.example."	`client_add`
"Elenca i miei clienti."	`client_list`
"Fattura ad Acme 12 ore a 90 EUR più 300 EUR di setup, IVA 23%, PDF."	`invoice_create` + `invoice_pdf`
"Fattura a Beta Corp 5 ore a 120 EUR."	`invoice_from_hours`
"Mostrami ogni fattura non pagata di agosto."	`invoice_list`
"Apri la fattura INV-2026-0007."	`invoice_get`
"Segna INV-2026-0007 come pagata per intero."	`invoice_mark_paid`
"Quali fatture sono non pagate e scadute?"	`overdue_report`
"Sono sul piano gratuito o Pro?"	`license_status`

Esempio pratico

Da docs/USER_VALUE_R2.md, la richiesta esatta testata end-to-end e verificata in modo indipendente rispetto all'aritmetica.

You: Invoice Acme for 12 hours of API work at 90 EUR plus a 300 EUR setup fee,
23% VAT, due in 14 days, and give me the PDF.

  invoice_create {
    client: "Acme", currency: "EUR", due_days: 14,
    items: [
      { description: "API work",  quantity: 12, unit_price: 90,  tax_rate: 23 },
      { description: "Setup fee", quantity: 1,  unit_price: 300, tax_rate: 23 }
    ]
  }
  -> INV-2026-0001, client "Acme" created with no address on file

  invoice_pdf { number: "INV-2026-0001" }
  -> /Users/you/.../invoice/pdf/INV-2026-0001.pdf

Assistant: Created INV-2026-0001 for Acme.
  API work    12 h  x  EUR 90.00   =  EUR 1080.00
  Setup fee    1    x  EUR 300.00  =  EUR 300.00
  Subtotal                            EUR 1380.00
  Tax 23% on EUR 1380.00               EUR 317.40
  Total                                EUR 1697.40
Note: Acme was created from a bare name with no address. Add one with
client_add before you send this. PDF: INV-2026-0001.pdf

L'aritmetica: 12 x 90 = 1080,00, più 300,00 = subtotale 1380,00; 23% di 1380,00 = 317,40; totale 1697,40 EUR. Ogni importo sul PDF e nella risposta testuale porta il suo codice valuta: nulla viene mai mostrato come numero nudo.

Gratuito vs Pro

	Gratuito	Pro
Fatture	3 per mese di calendario	Illimitate
`overdue_report`	Sì, illimitato	Sì, illimitato
PDF	Porta la riga "Generato con mcp-invoice di theluckystrike"	Nessun marchio
Logo sul PDF	No	Sì
Prefisso fattura personalizzato	No, fisso `INV`	Sì
Clienti, righe di imposta, sconti, pagamenti, multi-valuta	Sì	Sì

Pro è un pagamento unico di $19, oppure $39 per ogni server nella collezione, a vita.

Ottieni Pro: https://mcp.zovo.one/buy/invoice

Numeri e denaro

I numeri di fattura sono PREFIX-YYYY-NNNN. Il contatore è persistito per prefisso e anno e viene scritto prima che la fattura sia memorizzata, quindi un crash brucia un numero piuttosto che riutilizzarlo; vengono anche scansionati i numeri esistenti, così un file di dati ripristinato non può mai restituire un numero già presente su un documento inviato.

Ogni valore monetario stampato ovunque — prezzi unitari di riga, importi di riga, subtotale, sconto, ogni riga di imposta, il totale e il saldo dovuto, nella risposta testuale e sul PDF — porta il suo codice valuta, ad esempio EUR 1080.00. Nessun importo viene mai mostrato come numero nudo.

Tutti gli importi sono tenuti come unità minori intere. Quante ne servono per un'unità deriva da una tabella ISO 4217, non da un'ipotesi: 2 per la maggior parte delle valute, 0 per JPY, KRW, VND, CLP, ISK e il resto della lista a zero decimali, 3 per BHD, IQD, JOD, KWD, LYD, OMR e TND, 4 per CLF e UYW. KWD 1.234 è 1234 unità minori, non 123. La tabella è identica a quella in mcp-expense-tracker, perché i due server si scambiano importi e una valuta a 3 decimali in uno e a 2 nell'altro riscalerebbe il denaro per dieci. HUF ha 2 decimali: ISO 4217 gli dà due cifre minori anche se di solito è quotato senza. L'arrotondamento è per riga, poi sommato: il lordo di ogni riga viene arrotondato per primo, un discount_percent a livello di fattura viene applicato e arrotondato per riga, l'imposta viene calcolata e arrotondata per riga e poi raggruppata in una riga per aliquota, e i totali sono semplici somme intere di quei valori già arrotondati. Un totale stampato non può quindi mai essere in disaccordo con le righe stampate. Le date sono ISO YYYY-MM-DD.

Come memorizza i dati

Profilo aziendale, clienti, fatture e contatore numeri vivono sotto ${XDG_DATA_HOME:-~/.local/share}/mcp-servers/invoice/ come file JSON separati, più una sottocartella pdf/ che contiene i PDF generati. Ogni chiamata mutante (business_set, client_add, invoice_create, invoice_from_hours, invoice_mark_paid) viene eseguita dentro locked(), che prende un file di lock advisory a .../invoice/.lock per la durata della chiamata — questo è ciò che rende sicura l'allocazione dei numeri quando due fatture vengono create nello stesso secondo, poiché lettura del contatore, incremento e scrittura della fattura avvengono tutti sotto un unico lock. I salvataggi vanno su un file temporaneo e vengono rinominati in posizione. Per fare un backup dei tuoi dati di fatturazione, copia l'intera directory dati invoice/, inclusa pdf/ se vuoi anche i file generati — possono sempre essere rigenerati dai record memorizzati con invoice_pdf.

Se uno di quei file JSON è illeggibile o non è JSON valido, non viene mai trattato come "vuoto". Il file viene spostato da parte byte per byte come <name>.json.corrupt-<timestamp>, viene scritto un marcatore <name>.json.corrupt, e ogni strumento restituisce data file is corrupt; moved to ...; nothing was written finché non ripristini una buona copia ed elimini il marcatore. Un clients.json troncato non può più essere silenziosamente sostituito da una lista clienti vuota.

Limiti e avvertenze oneste

Il livello gratuito consente 3 fatture per mese di calendario; il contatore si azzera il 1°. overdue_report e tutto il resto (clienti, righe di imposta, sconti, pagamenti, multi-valuta) è illimitato nel gratuito.
I PDF gratuiti portano una piccola riga in fondo "Generato con mcp-invoice"; Pro la rimuove e aggiunge un logo.
Creare una fattura per un nome cliente mai visto dal server crea quel cliente senza indirizzo — la risposta lo dice e nomina client_add come soluzione, ma nulla ti blocca dall'inviare un PDF con un blocco BILL TO con solo nome se ignori la nota.
Non c'è invio email, link di pagamento o sincronizzazione con software contabile in questo server: produce il PDF e il record; farlo arrivare al cliente dipende da te.
La conversione di valuta non viene eseguita da nessuna parte — la valuta di una fattura è fissata alla creazione e ogni riga deve usare importi già in quella valuta.

Risoluzione dei problemi

npx si blocca o non trova il pacchetto: la pubblicazione npm per questo pacchetto è in sospeso. Usa il bundle .mcpb o il percorso clone+compilazione sopra finché non arriva.
Usare il bundle .mcpb: si installa direttamente in Claude Desktop; non c'è un passaggio di configurazione separato.
Usare il percorso clone: il binario del server è servers/invoice/dist/index.js dopo npm run build. Punta il command del tuo client a node con quel percorso assoluto come unico argomento.
Versione Node: richiede Node >= 18. Controlla con node -v.
Valute miste: una voce può avere il proprio currency. Ogni riga su una fattura deve concordare con la valuta della fattura; una combinazione viene rifiutata e il messaggio nomina la chiamata di conversione da fare (expense_to_invoice con target_currency e fx_rates) piuttosto che fatturare silenziosamente una riga in EUR sotto un'intestazione USD. Senza currency sulla fattura, un'unica valuta di voce concordata diventa quella della fattura.
Nessun profilo aziendale ancora: la fatturazione non è mai bloccata da questo. invoice_create e invoice_from_hours emettono il documento con l'emittente segnaposto "La tua attività" e lo dicono in una riga; esegui business_set {name, address, vat_id, iban} e genera di nuovo il PDF per sostituirlo.
Il rendering PDF fallisce o sembra sbagliato: invoice_pdf usa pdfkit, un renderer puramente JS senza dipendenza nativa, quindi i fallimenti sono quasi sempre un campo business_set mancante o malformato (controlla invoice_get prima) piuttosto che un problema di ambiente.
"3 fatture questo mese" raggiunto inaspettatamente: il limite gratuito è per mese di calendario su tutti i clienti, non per cliente. invoice_list mostra cosa ha già contato contro di esso.
Non appare nulla / fallimenti silenziosi: i log vanno solo su stderr, mai su stdout. In Claude Desktop controlla Impostazioni -> Sviluppatore -> il file di log del server; in Claude Code controlla il terminale o --mcp-debug.

Privacy

Tutti i dati restano locali, in ${XDG_DATA_HOME:-~/.local/share}/mcp-servers/invoice/. Non ci sono chiamate di rete: le chiavi di licenza sono verificate offline con una chiave pubblica compilata nel pacchetto, e i PDF sono generati sulla tua macchina.

Si abbina con

mcp-time-tracker — l'output invoice_summary lì si mappa direttamente sulle voci invoice_create qui.
mcp-spreadsheet — estrai voci o liste clienti da un foglio prima di fatturare.
mcp-price-tracker — fattura a un cliente qualcosa di cui hai tracciato il prezzo.
office-suite — tutti e quattro i server dietro un'unica installazione, una voce di configurazione.
Guida: Crea un PDF di fattura da un messaggio di chat con un server MCP

FAQ

Posso mettere più aliquote IVA su una fattura? Sì. L'aliquota fiscale è per voce. Il blocco totali stampa una riga di imposta per ogni aliquota distinta, quindi una riga al 23% e una riga a 0% con inversione contabile appaiono separatamente e il totale torna. ¿El PDF es lo suficientemente bueno para enviarlo al departamento de contabilidad de un cliente? Es una sola página A4 con bloques de emisor y cliente, fechas, una tabla de líneas con impuestos por línea, subtotal, líneas de impuestos, total y detalles de pago con IBAN y referencia. Añade la dirección del cliente con client_add primero; de lo contrario, BILL TO muestra solo el nombre.

¿Cuál es el formato del número de factura y puedo cambiarlo? INV-YYYY-NNNN, asignado en secuencia y nunca reutilizado. El prefijo es configurable con business_set; un prefijo distinto de INV es una función Pro.

¿Se sube algo cuando se renderiza el PDF? No. El renderizado es local con pdfkit, y los registros de facturas viven en ~/.local/share/mcp-servers/invoice/. El servidor no realiza ninguna llamada de red.

¿Qué tan exacta es la aritmética del dinero? Los montos son unidades menores enteras. Cada línea se redondea una vez, luego se suman las líneas, así que 12 h a 90 EUR más 300 EUR con 23% de IVA da 1380.00 más 317.40 = 1697.40 sin residuo de punto flotante.

Construido por theluckystrike.

Un perfil de negocio para toda la suite

Tu identidad se almacena una vez, en ${XDG_DATA_HOME:-~/.local/share}/mcp-servers/profile/business.json, y cada servidor de la suite la lee: el emisor de facturas, el membrete de docx, el emisor recurrente, la tasa de IVA predeterminada de expense-tracker, la zona horaria de time-tracker y timezone, y los membretes de currículum y contrato. Configúrala una vez con business_set (invoice o docx): nunca la repites en ningún otro lugar. Una dirección de correo electrónico solo se toma de ese perfil o de un argumento explícito; cuando no hay ninguna almacenada, los documentos muestran [add: email] y la herramienta lo indica en lugar de permitir que alguien improvise una dirección.