fattureincloud-mcp 1.6.4

MCP Server for Fatture in Cloud API - Italian electronic invoicing with Claude AI

Fatture in Cloud MCP Server

🇮🇹 Italiano | 🇬🇧 English

---

Italiano

Server MCP (Model Context Protocol) per integrare Fatture in Cloud con Claude AI e altri assistenti compatibili.

Permette di gestire fatture elettroniche italiane tramite conversazione naturale.

✨ Funzionalità (13 tool)

Tool	Descrizione
list_invoices	Lista fatture emesse per anno/mese
get_invoice	Dettaglio completo fattura
list_clients	Lista clienti con filtro
get_company_info	Info azienda collegata
create_invoice	Crea nuova fattura (bozza) con codice SDI automatico
duplicate_invoice	Duplica fattura esistente con codice SDI aggiornato
delete_invoice	Elimina fattura bozza (non inviata)
send_to_sdi	Invia fattura allo SDI
get_invoice_status	Stato fattura elettronica
send_email	Invia copia cortesia via email
list_received_documents	Fatture passive (fornitori)
get_situation	Dashboard: fatturato, incassato, costi
check_numeration	🆕 Verifica continuità numerica fatture

🚀 Installazione

Prerequisiti

• Python 3.10+
• Account Fatture in Cloud con API attive
• Claude Desktop o altro client MCP

1. Clona il repository

git clone https://github.com/aringad/fattureincloud-mcp.git
cd fattureincloud-mcp

2. Crea ambiente virtuale e installa dipendenze

python -m venv venv
source venv/bin/activate  # Linux/Mac
# oppure: venv\Scripts\activate  # Windows

pip install -r requirements.txt

3. Configura le credenziali

Copia il file di esempio e inserisci i tuoi dati:

cp .env.example .env

Modifica .env:

FIC_ACCESS_TOKEN=a/xxxxx.yyyyy.zzzzz
FIC_COMPANY_ID=123456
FIC_SENDER_EMAIL=[e-mail]

Come ottenere le credenziali:

1. Accedi a Fatture in Cloud
2. Vai su Impostazioni > API e Integrazioni
3. Crea un Token Manuale con i permessi necessari
4. Il COMPANY_ID è visibile nell'URL quando sei loggato

4. Configura Claude Desktop

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

{
  "mcpServers": {
    "fattureincloud": {
      "command": "/percorso/completo/fattureincloud-mcp/venv/bin/python",
      "args": ["/percorso/completo/fattureincloud-mcp/server.py"],
      "env": {
        "FIC_ACCESS_TOKEN": "a/xxxxx.yyyyy.zzzzz",
        "FIC_COMPANY_ID": "123456",
        "FIC_SENDER_EMAIL": "[e-mail]"
      }
    }
  }
}

5. Riavvia Claude Desktop

Chiudi completamente Claude Desktop (Cmd+Q su Mac) e riaprilo.

💬 Esempi d'uso

"Mostrami le fatture di dicembre 2024"
"Qual è la situazione finanziaria del 2025?"
"Duplica la fattura 310 cambiando 2025 in 2026"
"Invia la fattura 326 allo SDI"
"Manda la copia cortesia via email"
"Quali fatture devo ancora incassare?"
"Verifica la numerazione delle fatture 2025"

⚠️ Note di sicurezza

• Le operazioni di scrittura (create, send_to_sdi) richiedono sempre conferma
• L'invio allo SDI è irreversibile
• Le fatture vengono create come bozze (draft)
• Il codice univoco SDI viene recuperato automaticamente dall'anagrafica cliente
• Il metodo di pagamento di default è MP05 (bonifico)

📋 Changelog

Vedi CHANGELOG.md

📄 Licenza

MIT - Vedi LICENSE

👨‍💻 Autore

Sviluppato da Mediaform s.c.r.l. - Genova, Italia

---

English

MCP (Model Context Protocol) Server to integrate Fatture in Cloud with Claude AI and other compatible assistants.

Manage Italian electronic invoices through natural conversation.

✨ Features (13 tools)

Tool	Description
list_invoices	List issued invoices by year/month
get_invoice	Full invoice details
list_clients	List clients with filter
get_company_info	Connected company info
create_invoice	Create new invoice (draft) with automatic SDI code
duplicate_invoice	Duplicate existing invoice with updated SDI code
delete_invoice	Delete draft invoice (not yet sent)
send_to_sdi	Send invoice to SDI (Italian e-invoice system)
get_invoice_status	E-invoice status
send_email	Send courtesy copy via email
list_received_documents	Received invoices (suppliers)
get_situation	Dashboard: revenue, collected, costs
check_numeration	🆕 Verify invoice numbering continuity

🚀 Installation

Prerequisites

• Python 3.10+
• Fatture in Cloud account with API enabled
• Claude Desktop or other MCP client

1. Clone the repository

git clone https://github.com/aringad/fattureincloud-mcp.git
cd fattureincloud-mcp

2. Create virtual environment and install dependencies

python -m venv venv
source venv/bin/activate  # Linux/Mac
# or: venv\Scripts\activate  # Windows

pip install -r requirements.txt

3. Configure credentials

Copy the example file and fill in your data:

cp .env.example .env

Edit .env:

FIC_ACCESS_TOKEN=a/xxxxx.yyyyy.zzzzz
FIC_COMPANY_ID=123456
FIC_SENDER_EMAIL=[e-mail]

How to get credentials:

1. Log into Fatture in Cloud
2. Go to Settings > API and Integrations
3. Create a Manual Token with required permissions
4. The COMPANY_ID is visible in the URL when logged in

4. Configure Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (Mac) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "fattureincloud": {
      "command": "/full/path/to/fattureincloud-mcp/venv/bin/python",
      "args": ["/full/path/to/fattureincloud-mcp/server.py"],
      "env": {
        "FIC_ACCESS_TOKEN": "a/xxxxx.yyyyy.zzzzz",
        "FIC_COMPANY_ID": "123456",
        "FIC_SENDER_EMAIL": "[e-mail]"
      }
    }
  }
}

5. Restart Claude Desktop

Fully quit Claude Desktop (Cmd+Q on Mac) and reopen it.

💬 Usage examples

"Show me invoices from December 2024"
"What's the financial situation for 2025?"
"Duplicate invoice 310 changing 2025 to 2026"
"Send invoice 326 to SDI"
"Send the courtesy copy via email"
"Which invoices are still pending payment?"
"Check invoice numbering for 2025"

⚠️ Security notes

• Write operations (create, send_to_sdi) always require confirmation
• Sending to SDI is irreversible
• Invoices are created as drafts
• SDI unique code is automatically retrieved from client registry
• Default payment method is MP05 (bank transfer)

📋 Changelog

See CHANGELOG.md

📄 License

MIT - See LICENSE

👨‍💻 Author

Developed by Mediaform s.c.r.l. - Genova, Italy