home-remote-mcps

Puerta de enlace MCP remota personal. Expone Garmin Connect, Home Assistant y YouTube como servidores Model Context Protocol accesibles por HTTP, de modo que Claude (o cualquier cliente MCP) pueda consultarlos y controlarlos desde cualquier lugar — sin servidor local ni credenciales locales.

La autenticación para la interfaz web se delega en un SSO externo (home-auth, OAuth2). Los clientes MCP se autentican por separado con una clave de API por usuario emitida desde esa interfaz.

Por qué un sidecar para Garmin

Garmin Connect no tiene una API pública oficial ni un cliente Node con mantenimiento activo. El servicio garmin-connector es un sidecar Python pequeño, solo interno, que envuelve la librería garminconnect, la cual gestiona el flujo de inicio de sesión de Garmin (incluida la MFA) y la renovación del token. El backend NestJS se comunica con él a través de la red Docker con un secreto compartido; nunca se expone públicamente. Home Assistant y YouTube tienen API REST normales, por lo que el backend se comunica con ellos directamente.

Related MCP server: FitnessMCP

Estructura del proyecto

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

Consulta CLAUDE.md para ver la arquitectura detallada (capas, ruta de solicitudes MCP, diseño del conector por integración, modelo de autenticación) y ai-docs/ para material de referencia más profundo. Las guías orientadas a humanos están en docs/.

Requisitos

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

• Python >= 3.11 para garmin-connector

• Una instancia home-auth en ejecución (cliente OAuth2 registrado para esta aplicación) para el inicio de sesión en el navegador

• Docker, para despliegues en producción (deploy/docker-compose.yml)

Desarrollo local

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 debe coincidir entre backend/.env y garmin-connector/.env.

Compilar, probar, 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

Los hooks de Husky (pre-commit, pre-push, commit-msg) ejecutan lint-staged y commitlint (Conventional Commits) automáticamente.

Despliegue

El Dockerfile en la raíz del repositorio compila en varias etapas frontend → backend → una imagen de runtime que incluye Litestream para la replicación continua de SQLite a un bucket de MinIO (compatible con S3), restaurando al arrancar si MINIO_BUCKET está definido. garmin-connector/Dockerfile compila la imagen del sidecar por separado. deploy/docker-compose.yml ejecuta ambos como servicios hermanos en una red Docker interna: el sidecar no tiene puerto publicado, solo es accesible desde el backend en http://garmin-connector:8000. deploy/Caddyfile es la configuración del proxy inverso para el servicio público.

Las variables de entorno requeridas están documentadas en línea en backend/.env.example y garmin-connector/.env.example.