Garmin Connect MCP 서버

Garmin Connect에서 근력 운동을 위한 MCP 서버입니다. AI 어시스턴트와 대화하면서 세션을 설계하고, 시계로 푸시한 뒤, 실제로 수행한 운동을 다시 읽어올 수 있습니다.

비공식. Garmin과 제휴하거나 보증하거나 지원하지 않습니다. Garmin 및 Garmin Connect는 Garmin Ltd.의 상표입니다. 이 프로젝트는 리버스 엔지니어링된 python-garminconnect 클라이언트를 통해 Garmin의 비공개 운동 서비스 엔드포인트에 접속하므로, Garmin이 예고 없이 변경하거나 중단시킬 수 있습니다. 사용에 따른 책임은 본인에게 있으며, Garmin 서비스 약관에 따른 본인의 의무를 직접 확인하세요.

모든 것은 로컬에서 실행됩니다. 자격 증명은 사용자 머신에만 남으며 Garmin으로만 전송됩니다.

왜 필요한가

Garmin Connect는 운동 .FIT 파일을 가져오지 않습니다. FIT 가져오기는 완료된 활동에만 작동하며 계획된 운동에는 작동하지 않습니다. 선택지는 Connect 웹 UI를 수동으로 사용하거나, 웹 앱 자체가 호출하는 동일한 비공개 엔드포인트를 사용하는 것입니다. 이 프로젝트는 두 번째 방법을 사용하여 MCP 인터페이스를 얹어, 20분 동안 클릭하는 대신 대화에서 운동이 나올 수 있게 합니다.

도구

delete_workout만이 유일한 파괴적 도구입니다.

설정

Python 3.12 이상 필요 (garminconnect 0.3.x가 요구).

git clone https://github.com/YOUR-USERNAME/garmin-mcp.git
cd garmin-mcp
./setup.sh

setup.sh는 프로젝트 디렉터리에 .venv/를 만들고, 의존성을 설치하며, .env.example을 .env로 복사합니다. 시스템 전체에 설치되는 것은 없습니다. 가장 최신 Python에 아직 의존성용 휠이 없다면 다음으로 재정의하세요:

PYTHON=python3.13 ./setup.sh

.env에 Garmin 로그인 정보를 입력한 후 한 번 인증합니다:

./.venv/bin/python garmin_login.py

이 단계는 의도적으로 대화형입니다. Garmin이 MFA 코드를 요구할 수 있는데, MCP 서버에는 질문할 터미널이 없어 그냥 멈춰 버릴 수 있습니다. 로그인은 토큰을 ~/.garminconnect에 캐시하고, 서버는 이후부터 조용히 재사용합니다. 서버가 세션 만료를 보고할 때만 다시 실행하세요.

네트워크에 접촉하지 않고 빌드를 검증합니다:

./.venv/bin/python garmin_mcp.py --self-test

클라이언트에 연결

Claude Desktop

claude_desktop_config.json에 추가 — macOS는 ~/Library/Application Support/Claude/, Windows는 %APPDATA%\Claude\:

{
  "mcpServers": {
    "garmin": {
      "command": "/absolute/path/to/garmin-mcp/.venv/bin/python",
      "args": ["/absolute/path/to/garmin-mcp/garmin_mcp.py"]
    }
  }
}

절대 경로와 venv의 인터프리터를 사용하고 맨 python은 사용하지 마세요 — 앱은 셸의 PATH를 상속하지 않습니다. 이후 앱을 다시 시작하세요.

그 외

표준 stdio MCP 서버이므로 모든 클라이언트에서 작동합니다. 클라이언트 밖에서 디버깅하려면:

npx @modelcontextprotocol/inspector ./.venv/bin/python garmin_mcp.py

프로그램

프로그램은 다일 템플릿을 설명하는 programs/의 JSON 파일입니다. sync_program은 이름으로 매칭하여 프로그램의 모든 운동을 푸시합니다 — 기존 운동은 제자리에서 업데이트되고, 새 운동은 생성됩니다. 주석이 달린 템플릿은 programs/example.json을 참조하세요.

{
  "name": "Example Upper/Lower",
  "workouts": [
    {
      "name": "[EX] Upper A",
      "warmup": "Two or three ramp-up sets.",
      "blocks": [
        {
          "repeat": 4,
          "steps": [
            { "exercise": "Barbell Bench Press", "reps": 5, "weight_kg": 60,
              "note": "4x5-7. Add 2.5kg once you hit 7 on every set." },
            { "rest_seconds": 180 }
          ]
        }
      ]
    }
  ]
}

블록은 repeat 횟수만큼 실행되는 반복 그룹입니다. 스텝은 운동(exercise + reps, 선택적으로 weight_kg 및 note) 또는 휴식(rest_seconds)입니다. 슈퍼세트는 두 운동을 모두 담고 사이에 짧은 휴식, 끝에 긴 휴식을 두는 하나의 블록입니다. 맨몸 운동은 weight_kg을 생략하세요. 기본 준비 운동 스텝은 warmup을 생략하거나, 없애려면 ""로 설정하세요.

programs/*.json은 예제를 제외하고 gitignore 처리되므로, 자신의 훈련이 커밋에 들어가지 않습니다.

주의할 점

Garmin은 인식하지 못하는 운동 이름을 조용히 비웁니다. 업로드는 200을 반환하고, 운동은 세션 중간에 시계에서 이름 없이 표시됩니다. 이것이 search_exercises가 존재하는 이유이며, 모든 이름이 업로드 전에 카탈로그와 대조되는 이유입니다. 표시 이름은 아무도 입력하지 않는 방식으로 하이픈으로 연결됩니다 — "Rope Press-down", "Close-grip Chin-up" — 그래서 검색은 구두점을 정규화하고 "db", "bb", "ohp", "rdl", "skullcrusher" 같은 약어를 이해합니다.

API의 두 부분은 무게 단위에 대해 서로 다르게 봅니다. 운동 서비스는 weightUnit이 "factor": 1000.0을 담고 있음에도 weightValue를 킬로그램으로 받습니다. 활동 페이로드 — 실제로 든 무게 — 는 그램을 보고합니다. 둘 다 처리되므로 어느 쪽도 "고치지" 마세요.

왕복 검증은 단위 오류를 잡을 수 없습니다. Garmin이 저장한 것과 보낸 것을 비교하는데, Garmin은 보낸 것을 충실히 저장합니다. 그램을 보내던 시절에는 검사가 통과했고 Connect에 "75,000 kg"이 표시되었습니다. 첫 업로드는 Connect에서 직접 확인하세요.

삭제 후 재생성 대신 업데이트하세요. 운동 ID를 유지하면 시계가 변경을 편집으로 처리합니다. 재생성하면 기존 운동을 버리고 새로 가져오는데, 이것이 오래된 중복이 생기는 원인입니다.

429와 401은 같아 보입니다. Garmin은 IP당 로그인을 공격적으로 제한합니다. 첫 로그인 전송이 제한되면 garminconnect의 폴백이 오해를 부르는 401을 보고합니다. 직전에 429를 봤다면 제한입니다 — 30~60분 기다리고, 블록을 연장하는 루프로 재시도하지 마세요. 진짜로 잘못된 비밀번호인지 확인하려면: garmin_login.py --check-env.

구조

garmin_mcp.py       the server — tool definitions
garmin_core.py      auth, payload building, verification, set parsing
garmin_login.py     one-time interactive login (MFA lives here)
programs/           multi-day templates as JSON
setup.sh            creates .venv and installs dependencies

라이선스

MIT — LICENSE 참조.

python-garminconnect(MIT) 및 MCP Python SDK(MIT) 기반.