LibreLink MCP Server - Fixed for API v4.16.0
🩸 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-Idobbligatorio (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.keyse 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:
npm install keytar
Nota: Se
keytarnon può essere installato, il sistema userà automaticamente un file criptato come fallback.
2. Scarica il bundle
Usa il browser oppure:
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):
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:
- Apri Claude Desktop
- Vai su Impostazioni (Settings)
- Seleziona la scheda Estensioni (Extensions)
- Clicca su Impostazioni Avanzate (Advanced settings) e trova la sezione Extension Developer
- Clicca su "Installa Estensione..." (Install Extension…)
- Seleziona il file
.mcpb(librelink-mcp-server.mcpbscaricato al passaggio 1) - 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
# Clona il repository
git clone https://github.com/sedoglia/librelink-mcp-server.git
cd librelink-mcp-server
2. Installa le Dipendenze
# 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):
sudo apt-get install libsecret-1-dev gnome-keyring
Linux (Fedora/RHEL):
sudo dnf install libsecret-devel gnome-keyring
# Installa Keytar
npm install keytar
4. Compila il Progetto
# Compila TypeScript
npm run build
5. Configura le credenziali
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
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
{
"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
{
"current_glucose": 105,
"timestamp": "2025-12-06T16:30:00.000Z",
"trend": "Flat",
"status": "Normal",
"color": "green"
}
Statistiche
{
"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.keycon 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:
- Header
versioncon valore minimo4.16.0 - Header
Account-Idcontenente l'hash SHA256 dell'userId
La Soluzione
Questo fork genera automaticamente l'Account-Id dopo il login:
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
{"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:
- Apri l'app LibreLinkUp e accetta i nuovi Termini e Condizioni
- Verifica che qualcuno stia condividendo i dati con te
- Controlla di usare le credenziali LibreLinkUp (non LibreLink)
Errore di autenticazione
Soluzioni:
- Verifica email e password
- Prova ad accedere dall'app ufficiale LibreLinkUp
- Controlla la regione (EU vs US, ecc.)
Errore Keytar/Keychain
Se riscontri errori con il keychain:
- Assicurati che il servizio keychain del sistema sia attivo
- Su Linux, installa
libsecret-1-devegnome-keyring - Se Keytar non è disponibile, il sistema userà automaticamente il fallback file-based (
.encryption.keynella directory dati) - 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
📜 Licenza
MIT License
🙏 Crediti
- Fork originale: amansk/librelink-mcp-server
- Documentazione API: khskekec/libre-link-up-http-dump
- MCP Protocol: Anthropic
- Secure Storage: Keytar
☕ Supporta il Progetto
Se questo progetto ti è utile, considera di fare una donazione per supportarne lo sviluppo:
Disclaimer: Questo è un progetto non ufficiale, non affiliato con Abbott o FreeStyle Libre. Usalo responsabilmente e consulta sempre i professionisti sanitari per decisioni mediche.