garmin-mcp

Claude Desktop에 Garmin Connect의 러닝, 근력 운동 및 칼로리 데이터에 대한 읽기 전용 액세스를 제공하는 작은 MCP 서버입니다. 세 가지 도구가 있으며 설정하는 데 약 15분이 걸립니다.

저는 진행 상황을 추적하고, 다른 것들 중에서도 제 자신의 훈련 데이터를 분석하기 위해(예: 이지런 페이스가 어떻게 변했는지, 달리기도 한 날에 어떤 운동을 했는지) CSV를 수동으로 내보내지 않고 이 도구를 만들었습니다. Garmin의 Connect API와 직접 통신하므로 중간에 타사 서비스가 없으며 어떤 것도 업로드되지 않습니다.

도구

• list_runs(limit, start): 날짜, 러닝 유형, 거리, 시간, 평균 페이스, 평균 및 최대 심박수, 케이던스, 온도. 트레드밀 러닝도 포함합니다.

• list_strength(limit, start): 날짜, 세션 이름, 지속 시간, 세트, 횟수, 총 및 활동 칼로리, 평균 및 최대 심박수.

• daily_calories(days, end): 일일 총 칼로리, 활동 칼로리 및 기초 대사율 칼로리, 걸음 수 및 안정 시 심박수.

start는 행 오프셋이고 end는 날짜이므로, Claude는 최근 몇 개 항목만이 아니라 수년간의 기록을 페이지별로 넘길 수 있습니다.

모든 것은 읽기 전용입니다. 기본 라이브러리(garth-ng)는 쓰기 엔드포인트를 노출하지만, 여기서는 어떤 것도 호출하지 않습니다. 이것이 이 도구를 안전하게 만드는 유일한 요소입니다. 토큰 자체는 전체 계정에 대한 전체 액세스 권한을 부여하기 때문입니다.

요구 사항

Python 3.12+, uv, Claude Desktop 및 Garmin Connect 계정. 아래 명령어는 Unix 셸(macOS 또는 Linux)을 가정합니다. Windows에서도 작동하지만 경로가 다릅니다. Claude Desktop 자체는 macOS, Windows 및 Linux(베타, Ubuntu 및 Debian)에서 실행됩니다. Claude 모바일 앱이나 claude.ai에서는 작동하지 않습니다. 로컬 stdio 서버에는 연결할 URL이 없기 때문입니다.

설정

1. Garmin 비밀번호를 다른 곳에서는 사용하지 않는 것으로 변경하세요. 곧 스크립트에 입력해야 하기 때문입니다.

2. 클론 및 설치:

git clone https://github.com/SuvirRathore/garmin-mcp-public.git
cd garmin-mcp-public
uv sync

3. 한 번 인증합니다. 이렇게 하면 비밀번호가 ~/.garth에 저장된 OAuth 토큰으로 교환되며, 이후 비밀번호는 다시 필요하지 않습니다:

cd garmin-mcp-public
uv run auth_setup.py

메시지가 표시되면 MFA 코드를 입력하세요. OAuth1 토큰은 약 1년 동안 유효하며 OAuth2 토큰은 자체적으로 갱신되므로 대략 연간 한 번의 작업입니다. ~/.garth를 자격 증명으로 취급하세요. 이를 보유한 사람은 누구나 전체 Garmin 계정을 읽을 수 있습니다.

4. Claude를 사용하기 전에 도구를 직접 테스트합니다. 여기서 실패하면 MCP 문제가 아니라 인증 또는 엔드포인트 문제이며, Desktop의 로그를 통하는 것보다 이 수준에서 디버깅하는 것이 훨씬 빠릅니다:

cd garmin-mcp-public
uv run python -c "import server; print(server.list_runs(3))"
uv run python -c "import server; print(server.list_strength(3))"
uv run python -c "import server; print(server.daily_calories(7))"

5. 구성에 필요한 두 개의 절대 경로를 찾습니다:

cd garmin-mcp-public
which uv
pwd

6. Claude Desktop의 구성 파일을 만들거나 편집하고 아래 블록을 붙여넣고, 두 경로를 5단계의 출력으로 바꿉니다. 실제 경로를 붙여넣으면 YOUR_USERNAME의 두 인스턴스도 제거됩니다. 파일은 macOS의 경우 ~/Library/Application Support/Claude/claude_desktop_config.json에, Windows의 경우 %APPDATA%\Claude\claude_desktop_config.json에 있습니다. Linux 베타의 경우 현재 위치에 대한 Anthropic의 Claude Desktop 문서를 확인하세요.

{
  "mcpServers": {
    "garmin": {
      "command": "/Users/YOUR_USERNAME/.local/bin/uv",
      "args": ["--directory", "/Users/YOUR_USERNAME/path/to/garmin-mcp-public",
               "run", "server.py"]
    }
  }
}

두 경로 모두 절대 경로여야 합니다. Desktop은 최소 PATH로 서버를 시작하므로, 셸에서 작동하더라도 uv만으로는 실패합니다. 이미 다른 서버가 구성되어 있는 경우 객체를 교체하지 말고 garmin 항목을 그 옆에 추가하세요. TextEdit에서 이 파일을 편집하는 경우 먼저 스마트 따옴표를 끄세요. 중괄호 따옴표는 유효하지 않은 JSON입니다.

7. Claude Desktop을 완전히 종료하고(Cmd-Q, 창만 닫지 않음) 다시 엽니다. 구성은 시작 시에만 읽힙니다. 그런 다음 "지난 5번의 러닝과 이번 주 칼로리 소모량을 보여줘"와 같은 질문을 하고 도구 호출을 승인하세요.

작동하지 않는 경우

먼저 JSON의 유효성을 검사한 다음 서버의 stderr를 읽으세요. 다음 경로는 macOS 경로입니다. 플랫폼에 맞게 조정하세요:

cd garmin-mcp-public
uv run python -m json.tool ~/Library/Application\ Support/Claude/claude_desktop_config.json
tail -50 ~/Library/Logs/Claude/mcp-server-garmin.log

모든 호출에서 오류가 발생하면 일반적으로 토큰이 만료된 것입니다. auth_setup.py를 다시 실행하세요. Claude 내부의 "사용자 지정 커넥터 추가" 대화상자는 원격 HTTPS URL을 예상하므로 여기서는 관련이 없습니다.

이 도구를 확장하는 사람을 위한 참고 사항

Garmin의 Connect API는 문서화되지 않았으며 필드 이름이 변경되므로, 무언가가 비어서 반환될 때는 추측하지 말고 실제 객체 하나를 검사하세요. 다음을 리포지토리에 probe.py로 저장하고 셸에 붙여넣지 말고 uv run probe.py로 실행하세요:

import garth

garth.resume("~/.garth")
a = garth.connectapi(
    "/activitylist-service/activities/search/activities",
    params={"start": 0, "limit": 1},
)[0]
print(sorted(a))

도구를 추가하기 전에 알아야 할 두 가지 동작이 있습니다. activityType 필터는 상위 카테고리만 허용합니다. running은 작동하고 treadmill_running을 자동으로 포함하는 반면, strength_training은 HTTP 400을 반환하므로 fitness_equipment로 요청한 다음 Python에서 필터링해야 합니다. 또한 각 활동에는 약 100개의 필드가 있으므로 필요한 소수만 매핑하세요. 원시 Garmin JSON을 반환하면 모든 호출에서 컨텍스트 창이 넘쳐납니다.

같은 이유로 도구 수를 적게 유지하세요. 설명적인 독스트링이 있는 세 가지 집중된 도구가 12개의 모호한 도구보다 더 잘 작동합니다. 독스트링은 Claude가 호출할 도구를 선택할 때 읽는 내용이기 때문입니다.

MIT 라이선스.