Local Garmin Coach MCP

Private, single-user Garmin coaching tools for Codex/ChatGPT desktop and Claude. The server is local stdio only: no Cloudflare, Render, public URL, account service, or hosting cost.

The runtime is based on etweisberg/garmin-connect-mcp at commit 87d0ea059fb67f1ce65ac05100df74c3c3777c84. It keeps the upstream AGPL-3.0 license and Taxuspt attribution in NOTICE.

사전 요구 사항

• Node.js 20 이상

• pnpm 10.14.0

• Garmin Connect 계정 및 동기화된 시계

Related MCP server: io.github.matisdsp/fartlek

설치

cd /home/talvak/Desktop/repos/garmin-coach-mcp
pnpm install --frozen-lockfile
pnpm exec playwright install chromium
pnpm build
pnpm auth

pnpm auth는 전용 표시 Chrome 프로필을 엽니다. 수동으로 로그인하고 MFA를 완료한 다음 터미널에서 Enter를 누르세요. 브라우저 세션은 ~/.local/share/garmin-coach/browser-profile 아래에 유지됩니다. 런타임 CSRF 값은 현재 인증된 페이지에서 읽히며 저장되거나 출력되지 않습니다. 디렉터리는 0700, 파일은 0600이며 비밀번호 저장이 비활성화되고 사용자 이름/비밀번호 파일이 생성되지 않습니다.

Garmin의 프로필 쓰기 계약 캡처

Garmin은 안정적인 심박수 프로필 쓰기 API를 공개하지 않습니다. 서버는 이를 추측하지 않습니다.

pnpm capture:profile-contract

이 명령은 Garmin의 현재 앱 모델을 로드하고, 변경되지 않은 현재 기본 존을 저장하도록 요청한 다음, 결과 PUT을 전달 전에 차단합니다. 경로와 정확히 변경되지 않은 본문을 검증한 후, 편집된 메서드/경로/필드 형태와 지원되는 범위만 ~/.local/state/garmin-coach/profile-write-contract.json에 모드 0600으로 저장합니다.

Garmin의 형태가 입증될 수 없으면 계약이 저장되지 않으며 프로필 쓰기는 비활성화된 상태로 유지됩니다.

Codex 및 ChatGPT 데스크톱 연결

먼저 빌드한 다음 config/codex.toml.example을 ~/.codex/config.toml로 복사하거나, ChatGPT 데스크톱 설정 > MCP 서버를 통해 동일한 서버를 추가하세요. Codex CLI, IDE 확장 프로그램 및 ChatGPT 데스크톱은 같은 호스트에서 로컬 MCP 구성을 공유합니다.

예제는 다음을 사용합니다:

default_tools_approval_mode = "writes"

두 적용 도구 모두 명시적 approval_mode = "prompt"를 갖습니다. 구성 후 클라이언트를 다시 시작하고 /mcp를 사용하여 연결을 확인하세요.

ChatGPT 웹은 이 로컬 stdio 프로세스를 시작할 수 없습니다. Garmin 쓰기에는 ChatGPT 데스크톱/Codex를 사용하세요.

Claude 연결

config/claude.json.example을 Claude의 MCP 구성에 병합하거나 다음을 실행하세요:

claude mcp add garmin-coach -- /home/talvak/snap/code/current/.local/share/pnpm/node /home/talvak/Desktop/repos/garmin-coach-mcp/dist/index.js

파일시스템 잠금은 한 번에 하나의 로컬 클라이언트만 Garmin Chromium 프로필을 소유하도록 허용합니다. 다른 클라이언트를 사용하기 전에 한 클라이언트에서 서버를 중지하세요.

도구

안전한 워크플로

1. get_coaching_snapshot을 호출하고 Garmin Connect와 비교하세요.

2. preview_hr_profile_update를 호출하세요.

3. 모든 필드를 검토하고 정확한 표준 제안/해시를 승인하세요.

4. apply_hr_profile_update를 호출한 다음 Garmin을 동기화하고 시계 존을 시각적으로 확인하세요.

5. 일요일 시작 주 하나에 대해 preview_training_week를 호출하세요.

6. 회복 증거, 전체 페이로드, 경고 및 해시를 검토하세요.

7. 변경되지 않은 표준 제안/해시로 apply_training_week를 호출하세요.

8. verify_training_week를 호출하고 월요일/금요일이 135-149 bpm인지 확인하세요. 금요일은 고정 12% 지침을 표시해야 합니다.

9. 두 apply 호출을 다시 시도하여 멱등성을 입증하세요.

통증/부상 또는 질병은 운동 쓰기를 차단합니다. 회복은 유지, 감소 또는 건너뛰기가 가능하며 부하를 증가시키지 않습니다. 운동은 자동으로 삭제되지 않습니다.

Garmin은 Treadmill을 러닝 아래의 시계 활동으로 노출하며, 구조화된 운동 스포츠로는 노출하지 않습니다. 따라서 금요일은 Incline Walk 12%라는 러닝 호환 운동이며, 시계의 Treadmill 활동에서 시작하세요. 12% 경사 큐와 135-149 bpm 목표는 명시적으로 유지됩니다.

승인된 HR 프로필

이 값들은 잠정적입니다: 나이 27세, 안정 시 심박수 55, 추정 최대 심박수 189, 수동 LTHR 181. 자동 감지 플래그는 유지됩니다. 향후 변경에는 또 다른 미리보기와 승인이 필요합니다.

검증

일반 테스트는 오프라인이며 Garmin을 호출하지 않습니다:

pnpm test
pnpm lint
pnpm format:check
pnpm typecheck
pnpm build
git diff --check

동작은 spec.md를, 신뢰 경계는 docs/architecture.md를 참조하세요.

라이선스

AGPL-3.0. LICENSE 및 NOTICE를 참조하세요.