sedoglia/librelink-mcp-server

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

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

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,
  "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:

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:

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
├── 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

📄

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