garmin-mcp

Garmin Connect의 활동, 건강 및 트레이닝 데이터(활동, HRV, 수면, 심박수, 스트레스, 바디 배터리, 트레이닝 준비도, HR/파워 존, 젖산 역치, FTP, VO2max, 개인 기록, 운동, 예약된 운동, 트레이닝 플랜)를 Claude Desktop 내 도구로 노출하는 로컬 MCP 서버입니다.

garminconnect 라이브러리를 통해 실제 Garmin Connect API에 직접 연결합니다. 데이터는 읽기 전용이며, Garmin에 어떤 것도 다시 기록되지 않습니다.

인증 방식

Garmin 로그인은 의도적으로 두 곳에서 분리되어 있습니다.

• scripts/setup_auth.py — 직접 터미널에서 실행하는 대화형 스크립트입니다. 이메일/비밀번호로 로그인하고, Garmin이 요청하면 MFA 코드를 입력받아 생성된 세션 토큰을 ~/.garmin_mcp/tokens에 저장합니다.

• MCP 서버(src/garmin_mcp/server.py)는 Claude Desktop이 헤드리스로 실행하며, 캐시된 토큰을 로드하고 자동으로 갱신만 합니다. MFA를 요청하지 않습니다. Claude Desktop에는 프롬프트를 표시할 터미널이 없으며, 거기서 stdin을 기다리면 도구 호출이 중단되기 때문입니다. 캐시된 세션이 없거나 만료된 경우 도구 호출은 setup_auth.py를 다시 실행하라는 오류와 함께 실패합니다.

Garmin 비밀번호는 macOS 키체인(항목/서비스 garmin-mcp, Keychain Access에서 확인 가능)에 저장되며 파일에 기록되지 않습니다. Garmin 로그인 이메일(비밀 아님)만 ~/.garmin_mcp/config.json에 저장됩니다.

설치

1. 의존성을 설치합니다:

   cd garmin_mcp
   uv sync

2. 일회성 대화형 로그인을 실행합니다:

   uv run python scripts/setup_auth.py

   Garmin Connect 이메일과 비밀번호를 입력합니다(비밀번호는 다음 번을 위해 키체인에 저장됩니다). 메시지가 표시되면 MFA 코드를 입력합니다. 성공하면 확인 메시지와 토큰 캐시 경로가 표시됩니다.

3. ~/Library/Application Support/Claude/claude_desktop_config.json을 편집하고(다른 mcpServers 항목 옆에) 다음을 추가하여 Claude Desktop에 서버를 등록합니다:

   {
     "mcpServers": {
       "garmin": {
         "command": "uv",
         "args": ["run", "--project", "/Users/felix.guiony/Code/Perso/garmin_mcp", "garmin-mcp"]
       }
     }
   }

4. Claude Desktop을 완전히 종료(Cmd+Q, 창을 닫는 것만으로는 안 됨)하고 다시 엽니다. 도구/해머 아이콘에 garmin 도구가 표시되어야 합니다.

도구

모든 날짜 매개변수는 YYYY-MM-DD 형식을 사용하며 기본값은 오늘입니다.

문제 해결

도구 호출 시 "Garmin session error" / "run setup_auth.py" 메시지가 반환됩니다. 캐시된 갱신 토큰이 만료되었거나 해지되었습니다(비밀번호 변경이나 장기간 비활성 상태 후에 가끔 발생합니다). 다시 실행하세요:

uv run python scripts/setup_auth.py

속도 제한. Garmin Connect는 빠른 요청에 때때로 속도 제한을 적용합니다. 기본 라이브러리는 일시적인 오류를 자동으로 재시도하지만, 속도 제한 오류가 표시되면 잠시 기다렸다가 다시 시도하세요.

Claude Desktop 외부에서 서버를 직접 확인하려면:

uv run mcp dev src/garmin_mcp/server.py

MCP Inspector가 열려 각 도구를 직접 호출하고 출력/스키마를 확인할 수 있습니다.

프로젝트 구조

garmin_mcp/
  pyproject.toml
  src/garmin_mcp/
    auth.py      # keychain + token-cache helpers
    server.py    # FastMCP server and tool definitions
  scripts/
    setup_auth.py  # interactive one-time/occasional login