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.

📦 Ultima release: v4.6.0 — bundle .mcpb pronto da installare, con le note di rilascio, il file .sha256 per verificarlo e l'SBOM in formato CycloneDX.

📜 Cronologia delle versioni: tutte le modifiche dettagliate di ogni release — nuovi tool, correzioni, note di aggiornamento — sono nel CHANGELOG.

Strumenti

Il server espone 110 strumenti, raggruppati per argomento. I 26 contrassegnati con ✏️ scrivono sull'account Garmin; tutti gli altri leggono soltanto.

🏃 Attività

Elenco e ricerca

Dettaglio di una singola attività

Creazione e modifica

Confronti e analisi di periodo

❤️ Salute e benessere

Riepiloghi giornalieri

Passi, piani e minuti di intensità

Cuore e respiro

Stress ed energia

Sonno

Idratazione

Peso e composizione corporea

Pressione sanguigna

Salute femminile

📈 Allenamento e performance

Stato di forma

Carico di allenamento

Workout

Piani e percorsi

👟 Equipaggiamento

Equipaggiamento

Cataloghi Garmin

Collezioni

🏅 Obiettivi, badge e sfide

Obiettivi e record

Badge

Sfide

⚙️ Profilo, dispositivi e credenziali

Profilo

Dispositivi

Credenziali

Related MCP server: garmin-mcp

Prerequisiti

• Node.js 22.0 o superiore

• npm 8.0 o superiore

• Claude Desktop installato

• Account Garmin Connect con credenziali valide

🚀 Installazione Rapida (Bundle Precompilato)

Passaggi:

Il vault del sistema operativo è già incluso. Dalla v4.3.2 il bundle porta con sé i binari di keytar per ogni piattaforma (darwin-x64, darwin-arm64, win32-x64, win32-ia32, linux-x64, linux-arm64): non c'è niente da installare a parte l'estensione. Sulle architetture senza binario, e sulle sessioni Linux senza keyring attivo, la chiave finisce in un file protetto; check_credentials dice quale dei due è in uso.

1. Scarica il bundle

Usa il browser oppure:

wget https://github.com/sedoglia/garmin-mcp-ts/releases/latest/download/garmin-mcp-ts.mcpb

2. Verifica l'integrità

Verifica l'integrità (opzionale ma consigliato):

wget https://github.com/sedoglia/garmin-mcp-ts/releases/latest/download/garmin-mcp-ts.mcpb.sha256
sha256sum -c garmin-mcp-ts.mcpb.sha256

Accanto al bundle ogni release pubblica anche garmin-mcp-ts.sbom.cdx.json, l'elenco completo delle dipendenze contenute nel bundle: vedi SBOM (Software Bill of Materials).

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

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

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

keytar è una dipendenza opzionale: npm install lo compila o ne scarica il binario, e il vault nativo del sistema operativo viene usato senza altri passaggi. Se quel passaggio fallisce — è normale su una macchina senza toolchain di compilazione — il server ripiega su un file protetto e continua a funzionare; npm run check-encryption dice quale dei due è in uso.

3. Compila il Progetto

npm run build

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

4b. 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

"Mostrami i miei workout pianificati"

"Scarica il mio ultimo workout"

Training Readiness

"Qual è il mio Training Readiness di oggi?"

"Mostrami il mio Endurance Score"

Progressi e Statistiche

"Quanti km ho corso questo mese?"

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

Health Metrics Avanzati

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

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

Salute Femminile

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

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

Gestione Equipaggiamento

"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

"Mostrami i commenti sulla mia ultima attività"

"Imposta la mia ultima corsa come privata"

Metriche Training Avanzate

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

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

Analisi Attività

"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

Lo script esercita 91 dei 110 tool contro il tuo account Garmin: tutti quelli di sola lettura, più il ciclo di vita completo di un workout (crea → modifica → schedula → togli dal calendario → elimina) e quello di una collezione gear. Restano fuori i tre tool delle credenziali e i tool che scrivono altri dati sull'account — pesate, pressione, idratazione, attività manuali, upload, modifiche all'equipaggiamento — che vanno provati a mano su dati che sei disposto a perdere.

Architettura

garmin-mcp-ts/
├── src/
│   ├── index.ts           # Punto di ingresso, gestione stdout/stderr
│   ├── garmin/
│   │   ├── client.ts      # Client API Garmin Connect (~3700 righe)
│   │   ├── auth.ts        # Login, sessione e rinnovo dei token OAuth
│   │   └── simple-login.ts # Utility standalone per provare il login
│   ├── mcp/
│   │   ├── server.ts      # Setup server MCP e gestori richieste
│   │   ├── tools.ts       # Definizioni strumenti e schemi (110 tool)
│   │   └── handlers.ts    # Logica implementazione strumenti
│   ├── utils/
│   │   ├── constants.ts   # Costanti dell'applicazione, nomi dei tool compresi
│   │   ├── credentials.ts # Risoluzione delle credenziali fra estensione, vault e .env
│   │   ├── errors.ts      # Classi di errore personalizzate
│   │   ├── logger.ts      # Utility di logging (solo stderr)
│   │   ├── stdio-guard.ts # Impedisce ad altro codice di scrivere su stdout e rompere il protocollo
│   │   └── secure-storage.ts # Storage cifrato e accesso al vault del SO
│   ├── test-tools.ts      # Suite che esercita i tool su un account reale (npm test)
│   └── test-oauth.ts      # Diagnostica del flusso OAuth
├── scripts/
│   ├── setup-encryption.ts  # Script interattivo per setup credenziali
│   ├── check-encryption.ts  # Script diagnostico per verificare encryption
│   ├── sync-manifest.ts     # Rigenera e verifica manifest.json dal codice
│   ├── fetch-keytar-prebuilds.mjs # Scarica i binari keytar di tutte le piattaforme
│   └── test-keytar.ts       # Script diagnostico per testare l'integrazione con Keytar
├── vendor/keytar/         # Binari keytar per piattaforma, inclusi nel bundle
├── dist/                  # Output JavaScript compilato
├── manifest.json          # Manifest MCPB del bundle (generato in parte da sync-manifest)
├── PRIVACY.md             # Privacy policy referenziata dal manifest
├── CHANGELOG.md           # Cronologia delle versioni (CHANGELOG_EN.md in inglese)
├── package.json
└── tsconfig.json

📦 Costruire il bundle .mcpb

Il bundle pubblicato viene costruito dal workflow Release, che allega .mcpb, .sha256 e l'SBOM CycloneDX a una release in bozza. Si attiva in due modi:

• dal tag: git tag v4.3.1 && git push origin v4.3.1;

• a mano: Actions → Release → Run workflow, indicando il tag da pubblicare. Se non esiste ancora, il workflow lo crea dal ramo selezionato; se esiste, costruisce quello che il tag contiene.

La release nasce in bozza. La casella publish la pubblica: lanciando di nuovo il workflow sullo stesso tag con quella casella spuntata, la bozza esistente viene pubblicata senza toccarne gli allegati.

Pubblicata la release, riporta in locale quello che gli utenti scaricano:

npm run fetch:release            # l'ultima release pubblicata
npm run fetch:release -- v4.6.0  # un tag preciso

Gli allegati finiscono in releases/ (ignorata da git), presi dalla release stessa e non da un pack locale, e il .mcpb viene verificato contro il suo .sha256. È il file da inviare alla directory MCP o da aprire in Claude Desktop per provare la build spedita; lo script vede solo le release pubblicate, una bozza non conta.

Le note della release stanno in .github/release-notes/<tag>.md. Se il file esiste il workflow lo usa come testo della release, altrimenti ripiega sull'elenco automatico delle pull request. Per correggere il testo di una release già pubblicata basta modificare il file e rilanciare il workflow: gli allegati non vengono toccati.

In entrambi i casi il workflow rifiuta di procedere se il tag non corrisponde alla versione dichiarata nel manifest. La versione è dichiarata in cinque punti, che vanno alzati insieme prima di taggare: package.json, manifest.json, SERVER_VERSION in src/utils/constants.ts (è quella che il server annuncia nell'handshake MCP) e, in entrambi i README, il badge e la riga della release qui sopra. I link di download puntano invece a releases/latest e non vanno mai toccati. Alzata la versione, rigenera anche l'SBOM con npm run sbom: il componente radice ne riporta il numero, e check:sbom fallirebbe in CI.

Per costruire il bundle in locale:

npm ci
npm run pack        # build + controllo manifest + validazione + pack

Il bundle esce nella radice del repository come garmin-mcp-ts.mcpb, con il suo .sha256 accanto, ed è lo stesso che pubblica la release. mcpb pack archivia node_modules così come lo trova, quindi impacchettare l'albero di sviluppo direttamente ci infilerebbe anche TypeScript, tsx ed esbuild: una quindicina di MB che nessun utente carica mai. Per evitarlo scripts/pack.mjs copia in una directory temporanea le sole dipendenze di produzione — le stesse che il workflow installa con npm ci --omit=dev — e impacchetta quella.

Se cambi, aggiungi o rimuovi un tool, rigenera l'elenco dichiarato nel manifest:

npm run sync:manifest

npm run check:manifest fa fallire la CI quando manifest e codice divergono: la directory MCP legge il manifest e la risposta di tools/list, e un disallineamento fra i due si scopre altrimenti solo in fase di review.

📋 SBOM (Software Bill of Materials)

Un SBOM è l'inventario formale di tutto ciò che compone un software: ogni dipendenza, diretta e transitiva, con versione, licenza e provenienza. Serve a rispondere in fretta a domande come «questa release contiene la libreria X nella versione vulnerabile?» senza dover ricostruire l'albero delle dipendenze a mano. GitHub ne dà una buona introduzione in What is an SBOM?.

Questo progetto pubblica il proprio SBOM in formato CycloneDX 1.6 (JSON), lo standard OWASP / ECMA-424 letto dalla maggior parte degli strumenti di analisi:

• sbom.cdx.json nella radice del repository, che descrive il ramo main corrente;

• garmin-mcp-ts.sbom.cdx.json allegato a ogni release, che descrive esattamente il bundle pubblicato accanto:

  wget https://github.com/sedoglia/garmin-mcp-ts/releases/latest/download/garmin-mcp-ts.sbom.cdx.json

L'SBOM elenca le sole dipendenze che finiscono nel bundle .mcpb — quelle di produzione, più keytar che è opzionale — risolte da package-lock.json. Per ogni componente riporta nome, versione, licenza dichiarata, Package URL (pkg:npm/axios@1.20.0) e l'hash SHA-512 del tarball npm; la sezione dependencies conserva l'albero, così si vede da quale dipendenza diretta arriva ciascuna transitiva. Le dipendenze di sviluppo (TypeScript, tsx, il packer, il generatore stesso) non compaiono, per la stessa ragione per cui non sono nel bundle: nessun utente le carica.

Il file è generato con @cyclonedx/cyclonedx-npm in modalità riproducibile: niente numero di serie né timestamp, quindi cambia solo quando cambia una dipendenza. Si rigenera con:

npm run sbom

npm run check:sbom fa fallire la CI quando sbom.cdx.json non corrisponde più al lockfile, esattamente come check:manifest per il manifest; anche il workflow di release lo verifica prima di allegarlo.

Per interrogarlo, qualunque strumento che legga CycloneDX va bene. Due esempi con scanner di vulnerabilità che lavorano direttamente sull'SBOM, senza bisogno di node_modules:

grype sbom:sbom.cdx.json

trivy sbom sbom.cdx.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 (update_gear era rotto fino alla v4.5.3)

• ❌ Creazione gear (create_gear): NON DISPONIBILE - l'endpoint esiste ma il suo payload non è documentato: risponde 500 senza indicare quale campo rifiuti

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

La storia completa del progetto, versione per versione, è nel CHANGELOG.

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