home-remote-mcps

個人用リモートMCPゲートウェイ。Garmin Connect・Home Assistant・YouTube を Model Context Protocol サーバーとして公開し、HTTP経由でアクセスできるようにします。これにより、Claude（または任意のMCPクライアント）がどこからでもこれらを照会・制御できます。ローカルサーバーもローカル認証情報も不要です。

Web UIの認証は外部SSO（home-auth、OAuth2）に委任されます。MCPクライアントは、そのUIから発行されるユーザーごとのAPIキーで個別に認証します。

Garminにサイドカーを使う理由

Garmin Connectには公式の公開APIがなく、活発にメンテナンスされているNodeクライアントもありません。garmin-connector サービスは、Garminのログインフロー（MFAを含む）とトークン更新を処理する garminconnect ライブラリをラップする、内部専用の小さなPythonサイドカーです。NestJSバックエンドは共有シークレットを使ってDockerネットワーク経由で通信します。これは決して公開されません。Home AssistantとYouTubeには通常のREST APIがあるため、バックエンドは直接通信します。

Related MCP server: Sherpa MCP Server

プロジェクト構成

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/ にあります。

要件

• Node.js >= 20（.nvmrc を参照）

• garmin-connector 用に Python >= 3.11

• ブラウザログイン用に実行中の home-auth インスタンス（このアプリ用に登録されたOAuth2クライアント）

• プロダクションデプロイ用のDocker（deploy/docker-compose.yml）

ローカル開発

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 の間で一致している必要があります。

ビルド・テスト・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）を自動的に実行します。

デプロイ

リポジトリルートの Dockerfile は、フロントエンド → バックエンド → Litestream をバンドルしたランタイムイメージをマルチステージでビルドします。LitestreamはSQLiteの継続的レプリケーションをMinIO（S3互換）バケットに対して行い、MINIO_BUCKET が設定されている場合は起動時に復元します。garmin-connector/Dockerfile はサイドカーイメージを個別にビルドします。deploy/docker-compose.yml は両方を内部Dockerネットワーク上の兄弟サービスとして実行します。サイドカーには公開ポートがなく、バックエンドから http://garmin-connector:8000 でのみ到達可能です。deploy/Caddyfile は公開サービス用のリバースプロキシ設定です。

必要な環境変数は backend/.env.example と garmin-connector/.env.example にインラインで文書化されています。