Garmin Cache System - Multi-user Setup Guide

Multi-user Garmin Connect API med lokal SQLite caching och MCP support.

Features

• ✅ Multi-user support - Flera Garmin-konton
• ✅ Auto-login från .env - Autentisera vid första start
• ✅ 2FA support - Skriv MFA-kod i terminalen
• ✅ Separata tokens - Varje användare har egen cache
• ✅ Local caching - Minimerar API-anrop
• ✅ MCP integration - Claude Desktop, Open WebUI, etc

Setup - 3 enkla steg

1️⃣ Klona och installera

git clone https://github.com/lddlinden/garmin-cache-system.git
cd garmin-cache-system

# Python
python3 -m venv .venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate
pip install -r requirements.txt

# Node.js (för MCP senare)
npm install

2️⃣ Skapa .env med dina användare

Kopiera .env.example och lägg till dina Garmin-konton:

cp .env.example .env

Redigera .env:

GARMIN_USERS=ana:ana@mail.se:PASSWORD1,john:john@mail.se:PASSWORD2

BACKEND_HOST=127.0.0.1
BACKEND_PORT=8000

Format: alias:email:password,alias:email:password

3️⃣ Starta backend (första gången)

python backend.py

Första gången:

============================================================
🔐 GARMIN FIRST-TIME SETUP
============================================================

📝 Registering ana (ana@mail.se)...

🔑 Authenticating ana...
📱 MFA code required (check email/authenticator): 123456
✅ ana ready!

📝 Registering john (john@mail.se)...

🔑 Authenticating john...
📱 MFA code required (check email/authenticator): 654321
✅ john ready!

============================================================
✨ Setup complete - Backend starting...

🚀 Starting backend on 127.0.0.1:8000
INFO:     Uvicorn running on http://127.0.0.1:8000

Nästa gånger: Tokens är sparade, loggar in automatiskt!

Testa API

# Lista alla registrerade användare
curl http://localhost:8000/users

# Hämta aktiviteter för ana (user_id=1)
curl http://localhost:8000/activities/1?start=0&limit=5

# Hämta daglig summary
curl http://localhost:8000/daily-summary/1?date=2025-01-20

# Hjärtfrekvens
curl http://localhost:8000/heart-rate/1?date=2025-01-20

Databaskemata

-- Användare (sparas från .env)
CREATE TABLE garmin_users (
  id INTEGER PRIMARY KEY,
  alias VARCHAR UNIQUE,           -- "ana", "john"
  email VARCHAR UNIQUE,           -- din@mail.se
  password VARCHAR,               -- krypterad senare?
  authenticated INTEGER,          -- 1=autentiserad
  last_auth DATETIME
);

-- Cache (automatisk)
CREATE TABLE garmin_cache (
  id INTEGER PRIMARY KEY,
  user_id INTEGER,
  cache_key VARCHAR,              -- "activities_0_20"
  data TEXT (JSON),               -- komplett API response
  created_at DATETIME,
  expires_at DATETIME             -- auto-purge
);

CREATE INDEX ix_user_key ON garmin_cache(user_id, cache_key);

Cache TTL

• Aktiviteter: 2 timmar
• Daglig summary: 24 timmar
• Hjärtfrekvens: 24 timmar

Ändra i backend.py:

service.get_or_fetch(..., ttl_hours=12)  # 12 timmar istället

MCP Integration

Claude Desktop

1. Starta backend (Terminal 1):

python backend.py

2. Build MCP server (Terminal 2):

npm run build

3. Lägg till i ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "garmin": {
      "command": "node",
      "args": ["dist/mcp-server.js"],
      "cwd": "/path/to/garmin-cache-system",
      "env": {
        "BACKEND_URL": "http://localhost:8000"
      }
    }
  }
}

4. Restart Claude Desktop

Open WebUI

Samma setup, bara andra config-fil.

Fil-struktur

garmin-cache-system/
├── backend.py           ← FastAPI server
├── mcp-server.ts        ← MCP TypeScript
├── .env.example         ← Template
├── .env                 ← Din konfiguration (gitignore)
├── garmin_cache.db      ← SQLite database
├── .garmin-cache/       ← Token-mappar per user
│   ├── 1/               ← Ana's tokens
│   └── 2/               ← John's tokens
└── requirements.txt     ← Python deps

Felsökning

MFA inte triggad?

• Kontrollera att ditt Garmin-konto har 2FA aktiverat
• Väntande vid första autentiseringen - skriv MFA-koden från email

Fel: "User not authenticated"

# Rensa och starta om
rm garmin_cache.db
python backend.py

Check databas

sqlite3 garmin_cache.db
> SELECT alias, email, authenticated FROM garmin_users;

Nästa steg

1. ✅ Backend körandes
2. ⏳ Build MCP server: npm run build
3. ⏳ Koppla till Claude Desktop / Open WebUI
4. ⏳ Börja använda tools!

License

MIT

---

💡 Tips: Lägg .env i .gitignore (redan gjort) för att inte exponera lösenord!