Skip to main content
Glama

home-remote-mcps

Personal remote MCP gateway. Exposes Garmin Connect, Home Assistant, YouTube, personal health data, and Docker container logs (shipped to MinIO by Vector) as Model Context Protocol servers reachable over HTTP, so Claude (or any MCP 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 clients authenticate 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. The garmin-connector service is a small internal-only Python sidecar wrapping the garminconnect library, which handles Garmin's login flow (including MFA) and token refresh. The NestJS backend talks to it over the Docker network with a shared secret; it is never exposed publicly. Every other integration — Home Assistant, YouTube, personal health, and logs — has a normal REST (or S3-compatible) API, so the backend talks to them directly with no sidecar.

Related MCP server: Sherpa MCP Server

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 reference material. Human-oriented guides live in docs/.

Requirements

  • Node.js >= 26 (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 (vitest) then frontend (vitest)
npm run lint           # oxlint (type-aware)
npm run format          # oxfmt --write, repo-wide
npm run format:check
npm run typecheck

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 bundles Litestream for continuous SQLite replication to a MinIO (S3-compatible) bucket, restoring on boot if MINIO_BUCKET is set. garmin-connector/Dockerfile builds the sidecar image separately. deploy/docker-compose.yml runs both as sibling services on an internal Docker network — the sidecar has no published port, reachable only from the backend at http://garmin-connector:8000. deploy/Caddyfile is the reverse-proxy config for the public service.

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

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      D
      maintenance
      A unified data gateway MCP server that enables Claude to interact with multiple external REST and GraphQL APIs through OAuth 2.0 authentication.
      -
    • A
      license
      Not graded
      quality
      Not graded
      maintenance
      A read-only remote MCP server that lets Claude query your own Garmin Connect wellness and activity data — sleep, HRV, Body Battery, stress, heart rate, daily summaries, and workout details — through Garmin's official Personal API, with OAuth sign-in so it works from mobile and desktop clients.
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      A read-only MCP server that lets AI assistants query a user's own training, recovery, sleep, activity, and wellness data through the official Garmin Connect Personal API. It can run locally or be self-hosted on Cloudflare Workers for access from Claude and other MCP clients.
      27
      575 npm
      MIT