home-remote-mcps

Persönliches Remote-MCP-Gateway. Stellt Garmin Connect, Home Assistant und YouTube als Model Context Protocol-Server bereit, die über HTTP erreichbar sind, sodass Claude (oder ein beliebiger MCP-Client) sie von überall abfragen und steuern kann — ohne lokalen Server, ohne lokale Anmeldedaten.

Die Authentifizierung für die Web-UI wird an ein externes SSO (home-auth, OAuth2) delegiert. MCP-Clients authentifizieren sich separat mit einem pro Benutzer ausgestellten API-Schlüssel, der über diese UI vergeben wird.

Warum ein Sidecar für Garmin

Garmin Connect hat keine offizielle öffentliche API und keinen aktiv gepflegten Node-Client. Der Dienst garmin-connector ist ein kleiner, nur intern genutzter Python-Sidecar, der die Bibliothek garminconnect kapselt, die Garmins Anmeldeablauf (einschließlich MFA) und die Token-Aktualisierung übernimmt. Das NestJS-Backend kommuniziert über das Docker-Netzwerk mit ihm, wobei ein gemeinsames Geheimnis verwendet wird; er wird nie öffentlich exponiert. Home Assistant und YouTube haben normale REST-APIs, daher spricht das Backend sie direkt an.

Related MCP server: FitnessMCP

Projektstruktur

backend/            NestJS API — REST (auth, credentials, API keys) + MCP servers, DDD-ish layers
frontend/            React SPA — login, manage stored credentials, issue MCP API keys
garmin-connector/    FastAPI sidecar — Garmin Connect login/session via `garminconnect`
deploy/              docker-compose + Caddy config for production

Siehe CLAUDE.md für die detaillierte Architektur (Schichten, MCP-Anfragepfad, Connector-Design pro Integration, Authentifizierungsmodell) und ai-docs/ für weiterführendes Referenzmaterial. Für Menschen aufbereitete Anleitungen befinden sich in docs/.

Voraussetzungen

• Node.js >= 20 (siehe .nvmrc)

• Python >= 3.11 für garmin-connector

• Eine laufende home-auth-Instanz (für diese App registrierter OAuth2-Client) für die Browser-Anmeldung

• Docker für Produktions-Deployments (deploy/docker-compose.yml)

Lokale Entwicklung

npm install                    # installs backend + frontend workspaces

cp backend/.env.example backend/.env          # fill in home-auth + secrets, see comments in the file
cp garmin-connector/.env.example garmin-connector/.env

npm run dev:backend            # http://localhost:3000 (API under /api, Swagger under /api/docs)
npm run dev:frontend           # http://localhost:5173, proxies API calls to the backend

cd garmin-connector && pip install -r requirements.txt && uvicorn app.main:app --reload --port 8000

GARMIN_CONNECTOR_SECRET muss zwischen backend/.env und garmin-connector/.env übereinstimmen.

Build, Test, Lint

npm run build        # frontend, then backend (bundles frontend/dist into the backend build)
npm run test          # backend (jest) then frontend (vitest)
npm run lint           # eslint on both workspaces
npm run format          # prettier --write, repo-wide

Husky-Hooks (pre-commit, pre-push, commit-msg) führen lint-staged und commitlint (Conventional Commits) automatisch aus.

Bereitstellung

Das Dockerfile im Repository-Stammverzeichnis baut mehrstufig frontend → backend → ein Laufzeit-Image, das Litestream für kontinuierliche SQLite-Replikation in einen MinIO- (S3-kompatiblen) Bucket bündelt und beim Start wiederherstellt, wenn MINIO_BUCKET gesetzt ist. garmin-connector/Dockerfile baut das Sidecar-Image separat. deploy/docker-compose.yml führt beide als nebeneinander laufende Dienste in einem internen Docker-Netzwerk aus — der Sidecar hat keinen veröffentlichten Port und ist nur vom Backend unter http://garmin-connector:8000 erreichbar. deploy/Caddyfile ist die Reverse-Proxy-Konfiguration für den öffentlichen Dienst.

Erforderliche Umgebungsvariablen sind inline in backend/.env.example und garmin-connector/.env.example dokumentiert.