home-remote-mcps

home-remote-mcps

Personal remote MCP gateway. Exposes Garmin Connect, Home Assistant, and YouTube as ModelContext Protocol servers reachable over HTTP, so Claude (or anyMCP client) can query and control them from anywhere — no local server, no local credentials.

Authentication for the web UI is delegated to an external SSO (home-auth, OAuth2). MCP clientsauthenticate separately with a per-user API key issued from that UI.

Why a sidecar for Garmin

Garmin Connect has no official public API and no actively maintained Node client. Thegarmin-connector service is a small internal-only Python sidecar wrapping thegarminconnect library, which handles Garmin's loginflow (including MFA) and token refresh. The NestJS backend talks to it over the Docker networkwith a shared secret; it is never exposed publicly. Home Assistant and YouTube have normal RESTAPIs, so the backend talks to them directly.

Project layout

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

See CLAUDE.md for the detailed architecture (layering, MCP request path,per-integration connector design, auth model) and ai-docs/ for deeper referencematerial. Human-oriented guides live in docs/.

Requirements

• Node.js >= 20 (see .nvmrc)
• Python >= 3.11 for garmin-connector
• A running home-auth instance (OAuth2 client registered for this app) for browser login
• Docker, for production deploys (deploy/docker-compose.yml)

Local development

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 must match between backend/.env and garmin-connector/.env.

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) run lint-staged and commitlint(Conventional Commits) automatically.

Deployment

Dockerfile at the repo root multi-stage builds frontend → backend → a runtime image that bundlesLitestream for continuous SQLite replication to a MinIO (S3-compatible)bucket, restoring on boot if MINIO_BUCKET is set. garmin-connector/Dockerfile builds thesidecar image separately. deploy/docker-compose.yml runs both as sibling services on an internalDocker network — the sidecar has no published port, reachable only from the backend athttp://garmin-connector:8000. deploy/Caddyfile is the reverse-proxy config for the publicservice.

Required environment variables are documented inline in backend/.env.example andgarmin-connector/.env.example.