garmin-mcp

Garmin 데이터와 대화하세요. 읽기 전용 MCP 서버로, Claude와 ChatGPT가 훈련에 관한 질문에 답할 수 있게 해줍니다: 활동, 수면, HRV, Body Battery, 훈련 상태, 챌린지 리더보드 - 그리고 다른 Garmin MCP 서버와 달리, 시계가 기록한 원본 FIT 파일도 포함합니다. Connect-IQ 센서 채널(Stryd, Moxy/SmO2, CORE)까지 포함합니다.

You:  How did my last long run compare to the same route in June?
You:  Why is my training readiness so low this morning?
You:  Where do I stand in the running challenge, and who is ahead of me?
You:  Did my Stryd actually record power on Tuesday's session?

Garmin Connect에 절대 쓰지 않습니다. 모든 도구는 읽기 전용입니다.

세 가지 사용 방법

1. 게스트 액세스 - 인프라가 전혀 필요 없는 유일한 방법: 초대 링크를 열고, 계정을 만들고, Garmin을 연결하면 끝입니다. 방법 3과 마찬가지로 브라우저의 claude.ai와 ChatGPT에서 작동합니다 - 방법 2는 그럴 수 없습니다. 둘 다 사용자 컴퓨터에서 프로그램을 시작할 수 없기 때문입니다.

게스트 액세스는 아직 공개되지 않았습니다. 현재 소규모 테스터 그룹이 개인 초대를 통해 사용 중입니다. 공개적으로 초대를 요청할 수 있는 방법이 계획되어 있습니다 - 그때까지는 방법 2와 3을 오늘 바로 사용할 수 있습니다.

2. 로컬 - 어떤 것도 사용자 머신 밖으로 나가지 않습니다. 계정도, 서버도 없습니다. AI 클라이언트가 필요할 때 프로세스를 시작합니다. 어차피 Claude Desktop이나 Claude Code를 사용하고 모든 것을 로컬로 유지하려는 경우에 가장 좋습니다.

3. 자체 서버 - 게스트 액세스 뒤에 있는 것과 동일한 소프트웨어입니다. 직접 실행하고, 원하는 사람을 초대하고, 데이터를 소유하세요. docs/self-hosting.md를 참조하세요.

빠른 시작 (로컬)

uv tool install git+https://github.com/mskerwiderski/mcp-garmin

garmin-mcp login

로그인은 Garmin 이메일, 비밀번호, 그리고 사용 중이라면 다단계 인증 코드를 요청합니다. Garmin의 OAuth 토큰만 ~/.garmin-mcp/tokens.json에 모드 0600으로 저장합니다. 비밀번호는 어디에도 기록되지 않습니다.

그런 다음 클라이언트에 서버를 등록하세요:

claude mcp add garmin -- garmin-mcp serve

새 세션을 시작하고 질문하세요. Claude Desktop을 포함한 전체 안내는 docs/install-claude.md를 참조하세요.

문서

답할 수 있는 것

활동 - 스포츠와 날짜로 목록을 필터링하고, 단일 활동에 대한 Garmin의 자체 요약, 그리고 기기가 기록한 동일한 활동을 FIT 파일에서 직접 제공합니다. 파일의 모든 채널에 대한 시계열, 수영장 수영 세부 정보를 단일 길이까지, 그리고 실제로 데이터를 전달한 Connect-IQ 센서를 제공합니다.

건강 - 하루에 한 번 호출로 걸음 수, 안정 시 심박수, 스트레스, Body Battery, 점수가 포함된 수면 단계, HRV 상태 및 훈련 준비 상태를 제공합니다. 또한 부하 초점과 VO2max가 포함된 훈련 상태, 날짜 범위에 걸친 체성분과 혈압도 제공합니다.

추세와 계획 - 하루에 한 번 대신 한 번의 호출로 한 달 전체의 걸음 수, Body Battery 및 VO2max를 제공합니다. 훈련 계획 운동과 경주를 포함한 Garmin의 예정된 측면도 제공하므로 "계획된 것"과 "실제로 일어난 것"을 비교할 수 있습니다.

현재 위치 - 5km부터 마라톤까지의 경주 예측, 피트니스 나이, 지구력 및 언덕 점수, 평생 합계, 그리고 각 기록을 세운 활동이 포함된 개인 기록을 제공합니다.

맥락 - 역치와 심박수 구간, 활동, 킬로미터, 시간, 일수가 포함된 장비, 그리고 친구들과 경쟁하는 소셜 챌린지(현재 진행 중인 챌린지 포함)를 제공합니다.

전체 목록과 매개변수는 docs/tools.md를 참조하세요.

로그인이 사용자 머신에서 이루어지는 이유

Garmin의 SSO는 Cloudflare 뒤에 있으며, 2026년 3월부터 데이터센터 IP의 새 로그인에 429 또는 403으로 응답합니다. 따라서 garmin-mcp login은 사용자가 있는 곳에서 실행됩니다. 결과 OAuth1 토큰은 약 1년 동안 유효하며 connectapi.garmin.com에 대한 액세스 토큰을 발급하므로 로그인 후에는 sso.garmin.com을 다시 건드리지 않습니다.

호스팅 서버는 두 가지를 모두 제공합니다: 로그인 양식(비밀번호는 한 번만 사용되고 저장되지 않음)과 garmin-mcp export의 토큰 블록을 붙여넣는 방법입니다. Garmin이 서버 주소를 차단할 때 사용하는 방법입니다.

알아두면 좋은 점

이것은 Garmin의 내부 Connect API를 사용합니다 - 모든 커뮤니티 도구가 사용하는 것과 동일한 API입니다. 개인을 위한 공식 API는 없습니다. Garmin의 Health API는 파트너 프로그램입니다. 자신의 계정에만 사용하고, 호스팅 인스턴스는 실제로 아는 사람들에게만 유지하세요: 한 서버의 모든 계정은 Garmin에 대해 하나의 주소를 공유합니다.

응답은 의도적으로 작게 유지됩니다. Garmin은 활동당 수백 개의 필드와 수천 개의 포인트로 구성된 시계열로 응답합니다. 모든 것이 모델이 실제로 사용할 수 있는 수준으로 축소되며, 스트림은 채널별 min/max/avg로 리샘플링됩니다. 이것은 미용상의 문제가 아닙니다 - 원시 페이로드는 대화에 필요한 컨텍스트 창을 잡아먹을 것입니다.

개발

python3.12 -m venv .venv && .venv/bin/pip install -e ".[dev]"

.venv/bin/pytest

네트워크 액세스가 필요 없는 103개의 테스트 - Garmin API와 FIT 파일은 스텁 또는 합성됩니다. 구성 요소가 어떻게 맞물리는지에 대해서는 docs/architecture.md를 참조하세요.

라이선스

MIT. LICENSE를 참조하세요.