# LibreLink MCP Server - Fixed for API v4.16.0
🇬🇧 [English](README.en.md) | 🇮🇹 [Italiano](README.md)
🩸 Server MCP per accedere ai dati glicemici FreeStyle Libre tramite Claude Desktop.
**Questa è una versione corretta** che supporta le modifiche API introdotte l'8 ottobre 2025:
- ✅ Supporto per la versione API 4.16.0+
- ✅ Header `Account-Id` obbligatorio (SHA256 hash dell'userId)
- ✅ Gestione automatica del redirect regionale
- ✅ Refresh automatico del token
- ✅ Storage sicuro delle credenziali con crittografia AES-256-GCM
- ✅ Chiavi di crittografia salvate nel keychain del sistema operativo (Keytar)
- ✅ Fallback automatico a file `.encryption.key` se Keytar non disponibile
- ✅ Persistenza sicura dei token JWT
- ✅ **v1.3.0**: Supporto completo per tutte le 13 regioni LibreLinkUp
## 📋 Prerequisiti
- **Node.js**: Versione 18.0.0 o superiore
- **Account LibreLinkUp**: Account attivo con dati condivisi
- **Sensore**: FreeStyle Libre 2 o 3 attivo
- **Claude Desktop**: Per l'integrazione MCP
## 🚀 Installazione Rapida (Bundle Precompilato)
### Passaggi:
### 1. Installa Keytar (Raccomandato per sicurezza massima)
Per utilizzare il vault nativo del sistema operativo (Windows Credential Manager, macOS Keychain, Linux Secret Service), installa `keytar`:
```bash
npm install keytar
```
> **Nota:** Se `keytar` non può essere installato, il sistema userà automaticamente un file criptato come fallback.
### 2. Scarica il bundle
Usa il browser oppure:
```bash
wget https://github.com/sedoglia/librelink-mcp-server/releases/download/v1.3.0/librelink-mcp-server.mcpb
```
### 3. Verifica l'integrità
Verifica l'integrità (opzionale ma consigliato):
```bash
wget https://github.com/sedoglia/librelink-mcp-server/releases/download/v1.3.0/librelink-mcp-server.mcpb.sha256
sha256sum -c librelink-mcp-server.mcpb
```
### 4. Installa l'estensione in Claude Desktop (Metodo Consigliato)
**Installazione tramite Custom Desktop Extensions:**
1. Apri **Claude Desktop**
2. Vai su **Impostazioni** (Settings)
3. Seleziona la scheda **Estensioni** (Extensions)
4. Clicca su **Impostazioni Avanzate** (Advanced settings) e trova la sezione **Extension Developer**
5. Clicca su **"Installa Estensione..."** (Install Extension…)
6. Seleziona il file `.mcpb` (`librelink-mcp-server.mcpb` scaricato al passaggio 1)
7. Segui le indicazioni a schermo per completare l'installazione
> **Nota:** Questo è il metodo più semplice e consigliato. L'estensione sarà automaticamente integrata in Claude Desktop senza necessità di configurazione manuale.
---
### 5. Configura le Credenziali LibreLink (Metodo Sicuro - Raccomandato)
Apri una **nuova chat su Claude Desktop** e scrivi il seguente prompt:
```
Configura le credenziali di accesso per LibreLink
```
Rispondi al messaggio fornendo:
- **Utente:** la tua email LibreLink
- **Password:** la tua password LibreLink
L'estensione provvederà automaticamente a criptare e salvare le credenziali in modo sicuro nel vault nativo del sistema operativo (Windows Credential Manager, macOS Keychain, Linux Secret Service).
> **Nota:** Le credenziali NON verranno salvate in file di testo. Saranno sempre crittografate e gestite dal vault nativo del SO.
### 6. Riavvia Claude Desktop
- Chiudi completamente l'applicazione
- Riapri Claude Desktop
- Verifica in Impostazioni → Sviluppatore lo stato della connessione ✅
## 🚀 Installazione (clonando il repository con GIT)
### 1. Clona il Repository
```bash
# Clona il repository
git clone https://github.com/sedoglia/librelink-mcp-server.git
cd librelink-mcp-server
```
### 2. Installa le Dipendenze
```bash
# Installa dipendenze
npm install
```
### 3. Installa Keytar
Keytar richiede alcune dipendenze di sistema per funzionare:
**Windows**: Nessuna dipendenza aggiuntiva richiesta (usa Windows Credential Manager)
**macOS**: Nessuna dipendenza aggiuntiva richiesta (usa Keychain)
**Linux** (Debian/Ubuntu):
```bash
sudo apt-get install libsecret-1-dev gnome-keyring
```
**Linux** (Fedora/RHEL):
```bash
sudo dnf install libsecret-devel gnome-keyring
```
```bash
# Installa Keytar
npm install keytar
```
### 4. Compila il Progetto
```bash
# Compila TypeScript
npm run build
```
### 5. Configura le credenziali
```bash
npm run configure
```
Ti verrà chiesto:
- **Email**: Email del tuo account LibreLinkUp
- **Password**: Password del tuo account
- **Regione**: Una delle 13 regioni supportate (vedi sotto)
- **Range target**: Valori glicemici target (default: 70-180 mg/dL)
### Regioni Supportate
| Codice | Regione |
|--------|---------|
| AE | Emirati Arabi Uniti |
| AP | Asia Pacifico |
| AU | Australia |
| CA | Canada |
| CN | Cina |
| DE | Germania |
| EU | Europa (default) |
| EU2 | Europa 2 |
| FR | Francia |
| JP | Giappone |
| LA | America Latina |
| RU | Russia |
| US | Stati Uniti |
Le credenziali vengono salvate in modo sicuro:
- **Crittografia**: AES-256-GCM con salt e IV casuali
- **Chiave di crittografia**: Salvata nel keychain del sistema operativo
- **Token JWT**: Persistito in modo sicuro per evitare login ripetuti
### 6. Testa la connessione
```bash
npm run test:connection
```
### 7. Configura Claude Desktop
Aggiungi al file di configurazione di Claude Desktop:
**Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
```json
{
"mcpServers": {
"librelink": {
"command": "node",
"args": ["C:/percorso/librelink-mcp-server/dist/index.js"]
}
}
}
```
### 8. Riavvia Claude Desktop
Riavvia Claude Desktop per caricare il server MCP.
## 🛠 Strumenti MCP Disponibili
| Strumento | Descrizione |
|-----------|-------------|
| `get_current_glucose` | Lettura glicemica attuale con trend |
| `get_glucose_history` | Storico glicemico (default: 24 ore) |
| `get_glucose_stats` | Statistiche: media, GMI, time-in-range |
| `get_glucose_trends` | Analisi pattern: dawn phenomenon, stabilità |
| `get_sensor_info` | Info sensore attivo |
| `configure_credentials` | Configura credenziali LibreLinkUp |
| `configure_ranges` | Imposta range target personalizzati |
| `validate_connection` | Testa la connessione |
| `get_session_status` | Stato della sessione di autenticazione |
| `clear_session` | Pulisce la sessione e forza re-autenticazione |
## 💬 Esempi di Utilizzo
Una volta integrato con Claude Desktop, puoi chiedere:
- *"Qual è la mia glicemia attuale?"*
- *"Mostrami lo storico glicemico delle ultime 6 ore"*
- *"Calcola il mio time-in-range di questa settimana"*
- *"Analizza i miei pattern glicemici"*
- *"Ho il fenomeno dell'alba?"*
## 📊 Output di Esempio
### Lettura Attuale
```json
{
"current_glucose": 105,
"timestamp": "2025-12-06T16:30:00.000Z",
"trend": "Flat",
"status": "Normal",
"color": "green"
}
```
### Statistiche
```json
{
"analysis_period_days": 7,
"average_glucose": 112.5,
"glucose_management_indicator": 5.94,
"time_in_range": {
"target_70_180": 85.2,
"below_70": 2.1,
"above_180": 12.7
},
"variability": {
"standard_deviation": 28.4,
"coefficient_of_variation": 25.2
}
}
```
## 🔒 Sicurezza e Privacy
### Posizioni di Storage
I file di configurazione sono salvati in posizioni specifiche per ogni sistema operativo:
| Sistema | Percorso |
|---------|----------|
| Windows | `%LOCALAPPDATA%\librelink-mcp\` |
| macOS | `~/Library/Application Support/librelink-mcp/` |
| Linux | `~/.config/librelink-mcp/` |
### Architettura di Sicurezza
```
┌─────────────────────────────────────────────────────────────┐
│ Storage Chiave di Crittografia │
│ ┌─────────────────────────────────────────────────────────┐│
│ │ OPZIONE 1 (Preferita): OS Keychain via Keytar ││
│ │ - Windows: Credential Manager ││
│ │ - macOS: Keychain ││
│ │ - Linux: Secret Service (libsecret) ││
│ ├─────────────────────────────────────────────────────────┤│
│ │ OPZIONE 2 (Fallback): File .encryption.key ││
│ │ - Permessi 0o600 (solo proprietario) ││
│ │ - Usato se Keytar non disponibile ││
│ └─────────────────────────────────────────────────────────┘│
└─────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ [Percorso specifico per OS]/librelink-mcp/ │
│ ┌───────────────────┐ ┌────────────────────┐ │
│ │ credentials.enc │ │ token.enc │ │
│ │ (AES-256-GCM) │ │ (AES-256-GCM) │ │
│ │ - email │ │ - JWT token │ │
│ │ - password │ │ - expiration │ │
│ └───────────────────┘ │ - userId │ │
│ │ - accountId │ │
│ ┌───────────────────┐ └────────────────────┘ │
│ │ config.json │ │
│ │ (non sensibile) │ ┌────────────────────┐ │
│ │ - region │ │ .encryption.key │ │
│ │ - targetLow/High │ │ (fallback, 0o600) │ │
│ └───────────────────┘ └────────────────────┘ │
└─────────────────────────────────────────────────────────────┘
```
### Caratteristiche di Sicurezza
- **Crittografia AES-256-GCM**: Le credenziali sono crittografate con algoritmo AES-256 in modalità GCM con authentication tag
- **Salt e IV casuali**: Ogni operazione di crittografia usa salt e IV unici
- **Chiavi nel Keychain (preferito)**: La chiave master è salvata nel keychain del sistema operativo:
- Windows: Credential Manager
- macOS: Keychain
- Linux: Secret Service (libsecret)
- **Fallback file-based**: Se Keytar non è disponibile (es. LM Studio, ambienti senza moduli nativi), la chiave viene salvata in `.encryption.key` con permessi restrittivi (0o600)
- **Token persistenti**: I JWT token sono salvati crittografati per evitare login ripetuti
- **Migrazione automatica**: Le credenziali dalla vecchia versione vengono migrate automaticamente e le password in chiaro eliminate
- **Permessi file**: Automaticamente impostati a 600 (solo utente)
- **Nessun tracking**: Zero telemetria
- **Elaborazione locale**: Nessun dato inviato a server esterni
## ⚠️ Fix API v4.16.0 (Ottobre 2025)
### Il Problema
L'8 ottobre 2025, Abbott ha reso obbligatori:
1. Header `version` con valore minimo `4.16.0`
2. Header `Account-Id` contenente l'hash SHA256 dell'userId
### La Soluzione
Questo fork genera automaticamente l'`Account-Id` dopo il login:
```typescript
import { createHash } from 'crypto';
// L'userId viene dalla risposta del login
const userId = loginResponse.data.user.id;
const accountId = createHash('sha256').update(userId).digest('hex');
// L'header viene aggiunto a tutte le richieste autenticate
headers['Account-Id'] = accountId;
```
## 🐛 Troubleshooting
### Errore 403 con `minimumVersion`
```json
{"data":{"minimumVersion":"4.16.0"},"status":920}
```
**Soluzione:** Stai usando una versione vecchia. Usa questo fork aggiornato.
### Errore `RequiredHeaderMissing`
**Soluzione:** L'header `Account-Id` non viene inviato. Usa questo fork che lo include automaticamente.
### Nessuna connessione trovata
**Soluzioni:**
1. Apri l'app LibreLinkUp e accetta i nuovi Termini e Condizioni
2. Verifica che qualcuno stia condividendo i dati con te
3. Controlla di usare le credenziali LibreLinkUp (non LibreLink)
### Errore di autenticazione
**Soluzioni:**
1. Verifica email e password
2. Prova ad accedere dall'app ufficiale LibreLinkUp
3. Controlla la regione (EU vs US, ecc.)
### Errore Keytar/Keychain
Se riscontri errori con il keychain:
1. Assicurati che il servizio keychain del sistema sia attivo
2. Su Linux, installa `libsecret-1-dev` e `gnome-keyring`
3. Se Keytar non è disponibile, il sistema userà automaticamente il fallback file-based (`.encryption.key` nella directory dati)
4. Il fallback è completamente trasparente e le credenziali rimangono crittografate con AES-256-GCM
## 📁 Struttura Progetto
```
librelink-mcp-server/
├── src/
│ ├── index.ts # Server MCP principale
│ ├── librelink-client.ts # Client API con fix v4.16.0
│ ├── glucose-analytics.ts # Analisi e statistiche
│ ├── config.ts # Gestione configurazione
│ ├── configure.ts # Tool CLI configurazione
│ ├── secure-storage.ts # Storage sicuro con Keytar
│ └── types.ts # Definizioni TypeScript
├── test-real-connection.js # Test connessione
├── test-secure-storage.js # Test modulo sicurezza
├── package.json
├── tsconfig.json
└── README.md
```
## 🔐 Privacy Policy
Questo server MCP rispetta la tua privacy. Ecco un riepilogo:
- **Elaborazione locale**: Tutti i dati vengono elaborati esclusivamente sul tuo dispositivo
- **Crittografia**: Credenziali protette con AES-256-GCM, chiavi nel keychain OS
- **Nessun tracking**: Zero telemetria, analytics o condivisione con terze parti
- **Comunicazione sicura**: Solo con API LibreLinkUp ufficiali di Abbott
📄 **[Leggi la Privacy Policy completa](PRIVACY_POLICY.md)**
## 📜 Licenza
MIT License
## 🙏 Crediti
- Fork originale: [amansk/librelink-mcp-server](https://github.com/amansk/librelink-mcp-server)
- Documentazione API: [khskekec/libre-link-up-http-dump](https://gist.github.com/khskekec/6c13ba01b10d3018d816706a32ae8ab2)
- MCP Protocol: [Anthropic](https://modelcontextprotocol.io)
- Secure Storage: [Keytar](https://github.com/atom/node-keytar)
## ☕ Supporta il Progetto
Se questo progetto ti è utile, considera di fare una donazione per supportarne lo sviluppo:
[](https://paypal.me/sedoglia)
---
**Disclaimer**: Questo è un progetto non ufficiale, non affiliato con Abbott o FreeStyle Libre. Usalo responsabilmente e consulta sempre i professionisti sanitari per decisioni mediche.
