Garmin Connect MCP Server

English | Italiano

Un server Model Context Protocol (MCP) che connette Claude Desktop a Garmin Connect, permettendo di interrogare in linguaggio naturale i tuoi dati di attività fisica, metriche di salute, sonno e altro ancora.

🆕 Novità v4.3.0 - Correttezza dei dati restituiti dai tool

Diciannove tool restituivano dati vuoti, fittizi o semplicemente sbagliati. Ogni correzione è stata verificata contro un account Garmin reale.

🐛 DATI SBAGLIATI ✅ CORRETTO

• count_activities: restituiva sempre 0. Il servizio risponde con un array di bucket contenenti countOfActivities, mentre il codice leggeva un totalCount inesistente. Accetta ora startDate / endDate opzionali.

• get_training_status: restituiva il conteggio delle attività di tutta la vita più l'intero blob delle impostazioni utente. Ora usa l'endpoint dello stato di allenamento e accetta date al posto dell'inutile days.

• get_goals: errore 400 perché non inviava il parametro status. Senza status interroga ora tutti e tre gli stati e unisce i risultati.

• get_device_alarms: restituiva []. L'endpoint deviceservice/alarms non esiste: le sveglie fanno parte delle impostazioni del dispositivo. deviceId è ora opzionale.

• get_devices / get_device_last_used: restituivano entrambi le impostazioni utente invece di un elenco di dispositivi e dell'ultimo usato.

• get_personal_records: leggeva profile.personalRecords, campo inesistente.

• get_intensity_minutes / get_floors: gli endpoint usati rispondevano 404, quindi dichiaravano "nessun dato" anche per giornate piene.

• get_daily_summary: restituiva solo i passi più l'intera serie di frequenza cardiaca. Ora include calorie, distanza, piani, minuti di intensità, stress e Body Battery.

• get_body_composition: ignorava days e interrogava solo la giornata odierna.

• compare_activities / find_similar_activities: nel dettaglio attività le metriche stanno in summaryDTO, quindi i confronti producevano undefined e NaN.

• get_activity_splits: sempre vuoto, cercava i dati in un payload che non li contiene.

• get_race_predictions, get_training_load, get_load_ratio: endpoint errati o inesistenti, mascherati da "nessun dato".

• get_training_readiness, get_max_metrics, get_activity_hr_zones, get_activity_exercise_sets: forma della risposta errata (array espansi in oggetti del tipo {"0": ...}).

• get_progress_summary: filtrava solo le ultime 100 attività, troncando in silenzio i periodi più intensi.

✨ NUOVI PARAMETRI

• count_activities: startDate, endDate

• get_training_status: date (sostituisce days)

• get_device_alarms: deviceId ora opzionale, di default tutti i dispositivi

• get_intensity_minutes, get_body_composition: endDate

• find_similar_activities: searchDepth

• set_activity_privacy: livello subscribers ("solo connessioni")

Related MCP server: garmin-mcp

🆕 Novità v4.2.0 - Prima installazione e credenziali

🔐 CONFIGURAZIONE CREDENZIALI ✅ NUOVO

• Credenziali richieste durante l'installazione: Claude Desktop chiede email e password Garmin al momento dell'installazione del bundle. La password viene conservata nel vault del sistema operativo, mai in un file di testo.

• setup_credentials: nuovo tool per configurare le credenziali dalla chat, senza riavviare l'estensione.

• check_credentials: mostra se le credenziali sono configurate, da quale fonte provengono e dove sono archiviate (non restituisce mai la password).

• clear_credentials: elimina credenziali cifrate e token OAuth.

🐛 AVVIO DEL SERVER ✅ CORRETTO

• Il server non termina più all'avvio quando le credenziali mancano o sono errate: il transport MCP viene collegato per primo e il login avviene alla prima richiesta. L'errore Server transport closed unexpectedly su una installazione pulita è risolto, e al suo posto compare un messaggio che spiega cosa configurare.

• Le credenziali impostate nell'estensione hanno la precedenza sulla copia cifrata su disco, che viene riallineata automaticamente quando cambiano.

📈 Ora con 109 TOOLS disponibili!

🎉 Novità v4.1.0 - Gear Management & Collections

🔧 GEAR MANAGEMENT ✅ MIGLIORATO

• get_all_gear: ✅ ORA FUNZIONANTE - Lista automatica di tutto l'equipaggiamento (non richiede più UUID manuale!)

• create_gear: ❌ RIMOSSO (l'API OAuth Garmin restituisce 403 Forbidden per la creazione gear)

• update_gear: Aggiorna equipaggiamento (UUID ora ottenibile via get_all_gear)

• delete_gear: Elimina equipaggiamento (UUID ora ottenibile via get_all_gear)

🆕 GEAR METADATA & COLLECTIONS ✅ NUOVO

• get_gear_types: Ottieni i tipi di equipaggiamento disponibili (scarpe, bici, casco, etc.)

• get_gear_makes: Ottieni le marche/brand disponibili

• get_gear_collections: Lista tutte le collezioni di equipaggiamento

• get_gear_collection: Dettagli di una collezione specifica (gear associati, tipi attività)

• create_gear_collection: Crea una nuova collezione di equipaggiamento

• update_gear_collection: Aggiorna una collezione (nome, gear, tipi attività)

• delete_gear_collection: Elimina una collezione

📈 Ora con 106 TOOLS disponibili! (tutti testati e funzionanti)

Novità v4.1.0 - Social & Advanced Analytics

🤝 SOCIAL FEATURES ⚠️ PARZIALE

• get_activity_comments: Ottieni commenti su un'attività ✅ FUNZIONANTE

• add_activity_comment: Aggiungi commenti alle attività ❌ RIMOSSO (Non supportato da API OAuth Garmin)

• set_activity_privacy: Imposta privacy (public, private o subscribers)

📊 ADVANCED TRAINING METRICS ✅ TESTATO

• get_training_load: Carico di allenamento settimanale e bilanciamento

• get_load_ratio: Rapporto acuto/cronico (injury risk indicator)

• get_performance_condition: Condizione di performance attuale

💤 ADVANCED SLEEP ANALYSIS ✅ TESTATO

• get_sleep_movement: Movimenti durante il sonno e momenti irrequieti

⏰ DEVICE MANAGEMENT ✅ TESTATO

• get_device_alarms: Ottieni sveglie configurate sui dispositivi

🗺️ COURSE MANAGEMENT ✅ TESTATO

• get_courses: Ottieni percorsi/route salvati

🔬 ACTIVITY ANALYSIS TOOLS ✅ TESTATO

• compare_activities: Confronta 2-5 attività fianco a fianco

• find_similar_activities: Trova attività simili per tipo/distanza/durata (20% tolerance)

• analyze_training_period: Analisi completa trends, volumi e pattern di allenamento

Funzionalità

Questo server MCP fornisce 106 potenti strumenti per interagire con i tuoi dati Garmin Connect:

Strumenti Attività (Base)

Strumenti Salute & Benessere

Metriche Wellness (v1.2)

Strumenti Utente & Dispositivi

Nuovi Strumenti v2.0

Gestione Workout

Gestione Attività

Device & Settings

Health & Wellness Avanzati

Weight & Body

Activity Details Avanzati

Goals, Challenges & Records

Gear Management

Nota: A partire dalla v4.1, get_all_gear funziona automaticamente e fornisce gli UUID necessari per gli altri strumenti gear. La creazione di nuovo gear non è supportata dall'API OAuth di Garmin.

Reports & Progress

🆕 Nuovi Strumenti v3.0

User & Activity Summary

Health Metrics Avanzati

Badges & Challenges Avanzati

Gear Avanzato

Training Plans

Salute Femminile

Utility & Stats

🆕 Nuovi Strumenti v4.0

Social Features

Advanced Training Metrics

Advanced Sleep & Device

Activity Analysis

🆕 Nuovi Strumenti v4.1

Gear Metadata

Gear Collections (CRUD completo)

🆕 Nuovi Strumenti v4.2

Credenziali

Funzionano anche quando l'autenticazione a Garmin non è ancora possibile: sono il modo per configurarla.

Prerequisiti

• Node.js 18.0 o superiore

• npm 8.0 o superiore

• Claude Desktop installato

• Account Garmin Connect con credenziali valide

🚀 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/garmin-mcp-ts/releases/download/v4.3.0/garmin-mcp-ts.mcpb

3. Verifica l'integrità

Verifica l'integrità (opzionale ma consigliato):

wget https://github.com/sedoglia/garmin-mcp-ts/releases/download/v4.3.0/garmin-mcp-ts.mcpb.sha256
sha256sum -c garmin-mcp-ts.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 (garmin-mcp-ts.mcpb scaricato al passaggio 2)

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 Garmin

Durante l'installazione Claude Desktop mostra due campi, Garmin Email e Garmin Password: compilali con le credenziali del tuo account Garmin Connect. La password viene conservata nel vault nativo del sistema operativo (Windows Credential Manager, macOS Keychain, Linux Secret Service) e non viene mai scritta in chiaro.

Puoi rivedere o modificare i due campi in qualsiasi momento da Impostazioni → Estensioni → garmin-mcp-ts.

In alternativa, dalla chat: apri una nuova chat su Claude Desktop e scrivi:

Configura le credenziali di accesso per Garmin

Rispondi al messaggio fornendo:

• Utente: la tua email Garmin

• Password: la tua password Garmin

Claude usa il tool setup_credentials, che cifra e salva le credenziali nel vault nativo del sistema operativo e verifica subito l'accesso a Garmin Connect. Non serve riavviare.

Nota: Le credenziali NON verranno salvate in file di testo. Saranno sempre crittografate e gestite dal vault nativo del SO. Se hai compilato i campi dell'estensione, quei valori hanno la precedenza su quanto salvato da setup_credentials: per cambiarli, modificali in Impostazioni → Estensioni.

Per verificare la configurazione in qualsiasi momento:

Controlla lo stato delle credenziali Garmin

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

git clone https://github.com/sedoglia/garmin-mcp-ts.git
cd garmin-mcp-ts

2. Installa le Dipendenze

npm install

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

4. Compila il Progetto

npm run build

5. Configura le Credenziali Garmin (Metodo Sicuro - Raccomandato)

Esegui lo script di setup per configurare le credenziali in modo sicuro:

npm run setup-encryption

Questo script:

1. Crea una directory sicura nella home dell'utente

2. Genera una chiave di encryption e la salva nel vault nativo del SO

3. Chiede email e password Garmin

4. Cripta e salva le credenziali in modo sicuro

Per verificare la configurazione:

npm run check-encryption

5b. Metodo Alternativo (Legacy)

In alternativa, puoi creare un file .env nella root del progetto:

GARMIN_EMAIL=tua.email@esempio.com
GARMIN_PASSWORD=la_tua_password_garmin

Nota sulla Sicurezza: Non commitare mai il file .env nel controllo versione. È già incluso in .gitignore. Si consiglia di usare il metodo sicuro sopra descritto.

Configurazione di Claude Desktop

Posizione del File di Configurazione

Il file di configurazione di Claude Desktop si trova in:

• Windows: %APPDATA%\Claude\claude_desktop_config.json

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

• Linux: ~/.config/Claude/claude_desktop_config.json

Esempio di Configurazione

Aggiungi il server MCP Garmin al tuo claude_desktop_config.json:

{
  "mcpServers": {
    "garmin": {
      "command": "node",
      "args": ["C:\\percorso\\a\\garmin-mcp-ts\\dist\\index.js"]
    }
  }
}

Per macOS/Linux:

{
  "mcpServers": {
    "garmin": {
      "command": "node",
      "args": ["/percorso/a/garmin-mcp-ts/dist/index.js"]
    }
  }
}

Verifica della Configurazione

1. Riavvia Claude Desktop dopo aver salvato la configurazione

2. Cerca gli strumenti Garmin tra quelli disponibili (icona martello)

3. Prova a chiedere: "Quali sono le mie attività recenti su Garmin?"

Esempi di Utilizzo

Interrogare le Attività Recenti

"Mostrami le mie ultime 5 attività Garmin"

"Quali attività ho fatto questa settimana?"

Ottenere Metriche di Salute

"Quali sono le mie metriche di salute per oggi?"

"Quanti passi ho fatto ieri?"

Analisi del Sonno

"Come ho dormito la scorsa notte?"

"Mostrami i dati del sonno del 10 dicembre"

Gestione Workout (NUOVO v2.0)

"Mostrami i miei workout pianificati"

"Scarica il mio ultimo workout"

Training Readiness (NUOVO v2.0)

"Qual è il mio Training Readiness di oggi?"

"Mostrami il mio Endurance Score"

Progressi e Statistiche (NUOVO v2.0)

"Quanti km ho corso questo mese?"

"Mostrami il sommario dei miei progressi dell'ultimo mese"

Health Metrics Avanzati (NUOVO v3.0)

"Qual è stata la mia frequenza cardiaca a riposo oggi?"

"Mostrami gli eventi di tutto il giorno per stress e body battery"

Salute Femminile (NUOVO v3.0)

"Come influisce il mio ciclo mestruale sulla mia performance di allenamento?"

"In base al mio ciclo, quale tipo di allenamento dovrei fare?"

Gestione Equipaggiamento (NUOVO v4.0/v4.1)

"Mostrami tutto il mio equipaggiamento Garmin"

"Quali tipi di equipaggiamento posso gestire?"

"Crea una collezione 'Scarpe Running' e associala alle attività di corsa"

"Mostrami le mie collezioni di equipaggiamento"

Commenti e Privacy (NUOVO v4.0)

"Mostrami i commenti sulla mia ultima attività"

"Imposta la mia ultima corsa come privata"

Metriche Training Avanzate (NUOVO v4.0)

"Come sta andando il mio carico di allenamento questo mese?"

"Qual è il mio rapporto acuto/cronico? Sono a rischio infortuni?"

Analisi Attività (NUOVO v4.0)

"Confronta le mie ultime 3 corse"

"Trova attività simili alla mia corsa di domenica scorsa"

"Analizza il mio allenamento dell'ultimo mese"

Test

Esegui i test con dati reali:

npm test

Il test script verifica tutti gli strumenti con il tuo account Garmin.

Architettura

garmin-mcp-ts/
├── src/
│   ├── index.ts           # Punto di ingresso, gestione stdout/stderr
│   ├── garmin/
│   │   ├── client.ts      # Client API Garmin Connect (2200+ righe)
│   │   ├── types.ts       # Definizioni tipi TypeScript
│   │   └── simple-login.ts # Utility standalone per test login
│   ├── mcp/
│   │   ├── server.ts      # Setup server MCP e gestori richieste
│   │   ├── tools.ts       # Definizioni strumenti e schemi (109 tools)
│   │   └── handlers.ts    # Logica implementazione strumenti
│   └── utils/
│       ├── constants.ts   # Costanti dell'applicazione
│       ├── errors.ts      # Classi di errore personalizzate
│       ├── logger.ts      # Utility di logging (solo stderr)
│       └── secure-storage.ts # Modulo di storage sicuro con encryption
├── scripts/
│   ├── setup-encryption.ts  # Script interattivo per setup credenziali
│   ├── check-encryption.ts  # Script diagnostico per verificare encryption
│   └── test-keytar.ts       # Script diagnostico per testare l'integrazione con Keytar
├── dist/                  # Output JavaScript compilato
├── package.json
└── tsconfig.json

🔐 Architettura di Sicurezza

Il sistema di sicurezza utilizza un'architettura a due livelli per proteggere le credenziali:

Dove vengono salvati i dati

Come funziona

1. Chiave di Encryption: Una chiave AES-256 viene generata alla prima esecuzione e salvata nel vault nativo del SO

2. Credenziali: Email e password vengono cifrate con AES-256-GCM e salvate in garmin-credentials.enc

3. Token OAuth: I token vengono cifrati e salvati in garmin-tokens.enc per riutilizzo sessione

Perché è sicuro

• La chiave non è mai su disco in chiaro: È nel vault hardware/software del SO

• Se il repository viene esposto: I dati rimangono inutili senza la chiave

• Se il PC viene clonato: I dati sono inaccessibili (la chiave rimane nel vault dell'utente originale)

• Encryption forte: AES-256-GCM con IV casuale per ogni operazione

Fallback

Se keytar non è disponibile (vault nativo), il sistema usa un file .encryption.key con permessi ristretti (0o600) nella directory dati.

Verifica stato encryption

Per verificare lo stato completo dell'encryption e keytar:

npm run check-encryption

Per testare l'integrazione con keytar:

npm run test-keytar

⚠️ Limitazioni Note

Limitazioni API Garmin OAuth

Alcuni endpoint e funzionalità non sono disponibili tramite l'API OAuth pubblica di Garmin:

Commenti alle Attività

• ✅ Lettura commenti (get_activity_comments): Funzionante

• ❌ Scrittura commenti (add_activity_comment): NON SUPPORTATO dall'API OAuth

  • I commenti possono essere aggiunti solo tramite:

    • Web interface di Garmin Connect

    • App mobile Garmin Connect

    • NON disponibile via API OAuth

Privacy Attività

• ✅ Impostare privacy (set_activity_privacy): Funzionante

  • ✅ public: Funziona correttamente

  • ✅ private: Funziona correttamente

  • ✅ subscribers: Funziona correttamente (è "solo connessioni" in Garmin Connect)

  • ❌ followers: NON SUPPORTATO - non è una chiave valida, restituisce 400. La chiave corretta è subscribers

  Il livello attuale si legge da accessControlRuleDTO in get_activity_details: leggerlo prima di modificarlo evita di sovrascrivere subscribers con public.

Gear Management

• ✅ Lista gear (get_all_gear): Funzionante (via endpoint filterGear)

• ✅ Aggiorna/elimina gear (update_gear, delete_gear): Funzionante

• ❌ Creazione gear (create_gear): RIMOSSO - l'API OAuth restituisce 403 Forbidden

  • I gear possono essere creati solo tramite:

    • Web interface di Garmin Connect

    • App mobile Garmin Connect

• ✅ Collezioni gear (CRUD completo): Funzionante

Metriche Avanzate (Dipende dal Dispositivo)

Alcune metriche potrebbero non essere disponibili a seconda del modello di smartwatch:

Nota: Alcune metriche sono visibili nell'app Garmin Connect ma potrebbero non essere esposte tramite API OAuth.

Risoluzione dei Problemi

Problemi Comuni

Autenticazione Fallita

1. Verifica che le tue credenziali Garmin siano corrette

2. Controlla di poter accedere manualmente a connect.garmin.com

3. Assicurati che non ci siano caratteri speciali nella password che potrebbero richiedere escape

Rate Limiting (Errore 429)

Garmin potrebbe bloccare temporaneamente le richieste se ne vengono fatte troppe in un breve periodo. Attendi qualche minuto e riprova.

Il Server Non Appare in Claude Desktop

1. Controlla che il percorso a dist/index.js sia corretto e assoluto

2. Verifica che la sintassi del JSON di configurazione sia valida

3. Riavvia completamente Claude Desktop

4. Controlla i log di Claude Desktop per eventuali errori

Visualizzare i Log

Il server produce informazioni diagnostiche su stderr. In Claude Desktop, controlla i log dell'applicazione:

• Windows: %APPDATA%\Claude\logs\

• macOS: ~/Library/Logs/Claude/

Crediti e Ringraziamenti

Questo progetto è stato ispirato e costruito sul lavoro di diversi progetti open-source:

• Taxuspt/garmin_mcp - Implementazione originale Garmin MCP

• matin/garth - Libreria di autenticazione Garmin

• matin/garth-mcp-server - Server MCP basato su Garth

• Async-IO/pierre_mcp_server - Pattern per server MCP

• WillRaphaelson/garmin-mcp - Reference per API endpoints

Un ringraziamento speciale ai manutentori del pacchetto npm garmin-connect.

Contribuire

I contributi sono benvenuti! Sentiti libero di inviare una Pull Request.

1. Fai il fork del repository

2. Crea il tuo branch per la feature (git checkout -b feature/FunzionalitàIncredibile)

3. Committa le tue modifiche (git commit -m 'Aggiunge una FunzionalitàIncredibile')

4. Pusha il branch (git push origin feature/FunzionalitàIncredibile)

5. Apri una Pull Request

Licenza

Questo progetto è rilasciato sotto Licenza MIT - vedi il file LICENSE per i dettagli.

Privacy Policy

Questo progetto rispetta la tua privacy. Per informazioni complete su come vengono gestiti i tuoi dati, consulta la nostra Privacy Policy.

Riepilogo

• Dati raccolti: Credenziali Garmin (email e password) e token OAuth

• Archiviazione: Tutti i dati sono crittografati localmente con AES-256-GCM e salvati nel vault nativo del sistema operativo

• Trasmissione: I dati vengono trasmessi solo ai server Garmin Connect per l'autenticazione e il recupero dei dati

• Nessun server di terze parti: Non raccogliamo, non memorizziamo e non trasmettiamo i tuoi dati a server di terze parti

• Controllo locale: Tutti i dati rimangono sul tuo dispositivo sotto il tuo controllo

Disclaimer

Questo progetto non è affiliato, approvato o connesso a Garmin Ltd. o alle sue sussidiarie. Garmin e Garmin Connect sono marchi registrati di Garmin Ltd.

Supporta lo Sviluppo

Se questo progetto ti è utile, considera di supportarlo con una donazione!

English | Italiano | Segnala Problemi