home-remote-mcps

개인용 원격 MCP 게이트웨이입니다. Garmin Connect, Home Assistant, YouTube를 HTTP로 접근 가능한 Model Context Protocol 서버로 노출하여, Claude(또는 모든 MCP 클라이언트)가 어디서든 이들을 조회하고 제어할 수 있게 합니다 — 로컬 서버나 로컬 자격 증명이 필요 없습니다.

웹 UI 인증은 외부 SSO(home-auth, OAuth2)에 위임됩니다. MCP 클라이언트는 해당 UI에서 발급된 사용자별 API 키로 별도 인증을 수행합니다.

Why a sidecar for Garmin

Garmin Connect에는 공식 공개 API가 없고, 적극적으로 유지 관리되는 Node 클라이언트도 없습니다. garmin-connector 서비스는 Garmin의 로그인 흐름(및 MFA)과 토큰 갱신을 처리하는 garminconnect 라이브러리를 래핑하는 소규모 내부 전용 Python 사이드카입니다. NestJS 백엔드는 공유 비밀 키를 사용하여 Docker 네트워크를 통해 이 서비스와 통신하며, 이 서비스는 공개적으로 노출되지 않습니다. Home Assistant와 YouTube는 일반 REST API를 제공하므로 백엔드가 이들과 직접 통신합니다.

Related MCP server: FitnessMCP

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

상세 아키텍처(계층 구조, MCP 요청 경로, 통합별 커넥터 설계, 인증 모델)는 CLAUDE.md를, 더 깊은 참고 자료는 ai-docs/를 참조하세요. 사람을 위한 가이드는 docs/에 있습니다.

Requirements

• Node.js >= 20 (.nvmrc 참조)

• garmin-connector용 Python >= 3.11

• 브라우저 로그인을 위한 실행 중인 home-auth 인스턴스(이 앱에 등록된 OAuth2 클라이언트)

• 프로덕션 배포용 Docker(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은 backend/.env와 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 훅(pre-commit, pre-push, commit-msg)이 lint-staged와 commitlint(Conventional Commits)를 자동으로 실행합니다.

Deployment

리포지토리 루트의 Dockerfile은 멀티스테이지 빌드로 frontend → backend → 런타임 이미지를 생성하며, Litestream을 번들하여 MinIO(S3 호환) 버킷으로 SQLite를 지속적으로 복제하고, MINIO_BUCKET이 설정된 경우 부팅 시 복원합니다. garmin-connector/Dockerfile은 사이드카 이미지를 별도로 빌드합니다. deploy/docker-compose.yml은 두 서비스를 내부 Docker 네트워크에서 형제 서비스로 실행하며, 사이드카는 게시된 포트가 없어 http://garmin-connector:8000에서 백엔드만 접근할 수 있습니다. deploy/Caddyfile은 공개 서비스를 위한 리버스 프록시 설정입니다.

필요한 환경 변수는 backend/.env.example과 garmin-connector/.env.example에 인라인으로 문서화되어 있습니다.