home-remote-mcps

个人远程 MCP 网关。将 Garmin Connect、Home Assistant 和 YouTube 暴露为可通过 HTTP 访问的 Model Context Protocol 服务器，因此 Claude（或任何 MCP 客户端）可以从任何地方查询和控制它们——无需本地服务器，也无需本地凭据。

Web UI 的身份验证委托给外部 SSO（home-auth，OAuth2）。MCP 客户端使用从该 UI 签发的每用户 API 密钥单独进行身份验证。

为什么为 Garmin 使用 sidecar

Garmin Connect 没有官方的公共 API，也没有积极维护的 Node 客户端。garmin-connector 服务是一个仅限内部使用的小型 Python sidecar，封装了 garminconnect 库，该库处理 Garmin 的登录流程（包括 MFA）和令牌刷新。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）

• Python >= 3.11，用于 garmin-connector

• 一个正在运行的 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，用于将 SQLite 持续复制到 MinIO（S3 兼容）存储桶，并在设置了 MINIO_BUCKET 时在启动时恢复。garmin-connector/Dockerfile 单独构建 sidecar 镜像。deploy/docker-compose.yml 将两者作为兄弟服务运行在内部 Docker 网络上——sidecar 没有发布端口，只能从后端通过 http://garmin-connector:8000 访问。deploy/Caddyfile 是公共服务的反向代理配置。

必需的环境变量在 backend/.env.example 和 garmin-connector/.env.example 中进行了内联说明。