LibreLink MCP Server - Fixed for API v4.16.0

🇬🇧 English | 🇮🇹 Italiano

🩸 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

• ✅ v1.4.0: Aggiornamento dipendenze di sicurezza (13 vulnerabilità risolte), MCP SDK 1.29.0, richiede Node.js 20+

• ✅ v1.5.0: 8 vulnerabilità risolte, MCP SDK 1.30.0, richiede Node.js 22+

• ✅ v1.5.1: 5 vulnerabilità risolte (hono, qs), axios 1.20.0

• ✅ v1.6.0: get_glucose_stats riporta la finestra temporale effettivamente coperta (data_coverage), manifest del bundle completo, bundle senza devDependencies

📋 Prerequisiti

• Node.js: Versione 22.0.0 o superiore

• Account LibreLinkUp: Account attivo con dati condivisi

• Sensore: FreeStyle Libre 2 o 3 attivo

• Claude Desktop: Per l'integrazione MCP

Related MCP server: dexcom-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 keytar non 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.6.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.6.0/librelink-mcp-server.mcpb.sha256
sha256sum -c librelink-mcp-server.mcpb.sha256

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

# 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

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

💬 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,
  "data_coverage": {
    "from": "2026-09-12T10:46:28.000Z",
    "to": "2026-09-12T22:01:32.000Z",
    "hours_covered": 11.3,
    "hours_requested": 168,
    "note": "Only 11.3 of the requested 168 hours are available: LibreLinkUp returns roughly the last 12 hours of readings. Statistics below describe that window only."
  },
  "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
  }
}

Il blocco data_coverage indica la finestra temporale realmente coperta dalle letture: LibreLinkUp restituisce solo le ultime ~12 ore, quindi le statistiche descrivono quella finestra anche quando si richiedono più giorni.

🔒 Sicurezza e Privacy

Posizioni di Storage

I file di configurazione sono salvati in posizioni specifiche per ogni sistema operativo:

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

🧾 SBOM (Software Bill of Materials)

Il progetto pubblica un SBOM in formato CycloneDX 1.6: l'inventario completo, leggibile da macchina, di tutto il codice di terze parti che gira sul tuo dispositivo quando usi il server.

• File: sbom.cdx.json nella radice del repository; è incluso anche dentro il bundle .mcpb e allegato a ogni release GitHub.

• Contenuto: le sole dipendenze di produzione (quelle che finiscono nel bundle), dirette e transitive, con versione, licenza, Package URL, hash SHA-512 del tarball npm e grafo delle dipendenze. Le devDependencies (typescript, @types/*) sono escluse perché non vengono distribuite.

• Generazione: prodotto da @cyclonedx/cyclonedx-npm a partire dal solo package-lock.json, in modalità riproducibile (senza timestamp né numero di serie): lo stesso lockfile produce sempre lo stesso inventario, quindi un diff sull'SBOM segnala esclusivamente un cambio di dipendenze.

• Allineamento garantito: la CI rigenera l'SBOM a ogni push e PR (npm run sbom:check) e fallisce se non coincide con quello committato, così il file su main descrive sempre il lockfile corrente. Chi aggiorna una dipendenza deve quindi rilanciare npm run sbom e committare il risultato insieme a package-lock.json; sulle PR di Dependabot lo fa in automatico il workflow dependabot-sbom.yml.

Per rigenerarlo o per usarlo con uno scanner di vulnerabilità (es. Grype, OSV-Scanner, Dependency-Track):

npm run sbom
grype sbom:sbom.cdx.json

⚠️ 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:

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:

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
├── scripts/
│   ├── smoke-test.mjs        # Smoke test MCP senza credenziali (CI)
│   ├── sbom-check.mjs        # Verifica che l'SBOM coincida col lockfile (CI)
│   └── pack.mjs              # Build del bundle .mcpb di release
├── manifest.json             # Manifest del bundle .mcpb
├── sbom.cdx.json             # SBOM CycloneDX delle dipendenze di produzione
├── test-real-connection.js   # Test connessione
├── test-secure-storage.js    # Test modulo sicurezza
├── package.json
├── tsconfig.json
└── README.md

📦 Pubblicare una release (per i maintainer)

Il numero di versione è dichiarato in sei file, che devono cambiare insieme: package.json, package-lock.json, manifest.json (il bundle .mcpb), src/index.ts (costruttore Server e banner di avvio) e i due README (riga di changelog + URL di download del bundle).

1. Branch e bump

   git checkout -b release/X.Y.Z
   npm version X.Y.Z --no-git-tag-version   # package.json + package-lock.json

   Poi aggiorna a mano manifest.json, src/index.ts, README.md e README.en.md.

2. Verifica

   npm run typecheck && npm run build
   npm run pack
   npm audit --audit-level=moderate

   npm run pack compila, reinstalla le sole dipendenze di produzione, esegue lo smoke test su quell'albero (che controlla anche che la versione riportata via MCP coincida con package.json), rigenera sbom.cdx.json, impacchetta releases/librelink-mcp-server.mcpb con il relativo .sha256 e infine ripristina le devDependencies. Così il bundle non contiene mai typescript o @types/*, e l'SBOM (che riporta la nuova versione e le dipendenze aggiornate) va committato insieme al bump.

3. Pull request con il template dedicato (le PR ordinarie e quelle di Dependabot non lo usano):

   gh pr create --template release.md

   Il merge su main richiede la CI verde.

4. Tag e release dopo il merge:

   git checkout main && git pull --ff-only
   git tag -a vX.Y.Z -m "vX.Y.Z" && git push origin vX.Y.Z
   npm run pack
   gh release create vX.Y.Z releases/librelink-mcp-server.mcpb releases/librelink-mcp-server.mcpb.sha256 sbom.cdx.json \
     --title "LibreLink MCP Server vX.Y.Z" --latest --notes-file NOTE.md

5. Controllo finale: scarica gli asset pubblicati e verifica il checksum, esattamente come farà un utente.

   gh release download vX.Y.Z -p 'librelink-mcp-server.mcpb*'
   sha256sum -c librelink-mcp-server.mcpb.sha256

🔐 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.