garmin-mcp

Cloudflare Workers(무료 티어)에서 Garmin Connect용 원격 MCP 서버입니다. taxuspt/garmin_mcp의 전체 TypeScript 포트로, 138개 전체 도구와 garmin_get 패스스루(총 139개), 그리고 5개의 운동 템플릿/참조 MCP 리소스를 포함합니다.

모듈: 활동 관리(21), 건강 및 웰니스(29), 트레이닝 및 성과(15), 운동 및 빌더(19), 영양(14), 챌린지/기기/장비(18), 체중/신체/여성 건강/코스(14), FIT 파일 분석(4), 사용자 프로필(4), 패스스루(1).

인증: 이 서버는 OAuth 2.1 인가 서버(@cloudflare/workers-oauth-provider 기반)입니다. MCP 클라이언트에 추가하면 브라우저 페이지가 열리고, 여기에 Garmin 이메일과 비밀번호(계정에 2FA가 설정된 경우 MFA 코드 포함)를 입력합니다. Worker는 Garmin의 SSO 웹 위젯 로그인 흐름을 서버 측에서 실행합니다(데이터센터 IP에서 봇 차단을 당하지 않는 유일한 로그인 경로). 이를 통해 장기(약 1년) 유효한 OAuth1 토큰을 획득하고, 사용자 자격 증명은 폐기한 채 해당 토큰만 암호화하여 grant에 저장합니다. 그런 다음 connectapi.garmin.com용 단기 OAuth2 베어러 토큰을 필요할 때마다 발급합니다. Garmin이 서버 측 로그인을 차단하기 시작할 경우를 대비해, (아래 로컬 스크립트를 통한) "토큰 붙여넣기" 대체 수단이 details 토글 뒤에 숨겨져 있습니다.

배포

1. npm install

2. npx wrangler kv namespace create OAUTH_KV — 반환된 id를 wrangler.jsonc에 붙여넣습니다.

3. npx wrangler deploy

Related MCP server: Garmin Open MCP

클라이언트 연결

claude mcp add garmin --transport http https://garmin-mcp.<your-subdomain>.workers.dev/mcp

Claude Code가 브라우저에서 인증 페이지를 엽니다. 안내에 따라 두 단계를 진행하세요. claude.ai 웹: 설정 → 커넥터 → 동일한 URL로 사용자 지정 커넥터 추가. Claude Desktop 및 기타 stdio 전용 클라이언트도 mcp-remote가 OAuth 흐름을 처리합니다.

액세스는 OAuth 전용입니다. 원시 헤더 경로는 없습니다. 모든 /mcp 요청은 공급자가 발급한 액세스 토큰으로 게이트되며, 액세스 토큰은 로그인 흐름을 완료해야만 발급됩니다.

내 계정으로 잠그기

wrangler.jsonc의 OWNER_GARMIN_IDS를 본인의 Garmin displayName(get_user_profile이 반환하는 값)으로 설정하세요. 쉼표로 구분된 허용 목록입니다. 목록에 없는 Garmin 계정으로 로그인하면 인증 단계에서 거부되므로, 타인이 유효한 Garmin 자격 증명을 가지고 있더라도 배포본을 사용할 수 없습니다. 비워 두면 모든 Garmin 계정을 허용합니다.

원본과의 차이점(원격/서버리스 적응)

• download_activity_file은 로컬 디스크에 쓰는 대신 파일 콘텐츠를 인라인으로 반환합니다(fit은 base64, gpx/tcx/csv는 텍스트, 크기 제한 있음). set_fit_download_dir은 문서화된 no-op입니다.

• upload_course는 로컬 파일 경로 대신 gpx_content(GPX XML 텍스트)를 받습니다.

• get_activity_fit_data는 세션/랩/레코드 및 파워 분석(NP, VI, 파워 커브, W/kg)을 다룹니다. 원본의 Di2 시프트, 언덕 감지, HRV 분석은 포팅되지 않았습니다.

• 무료 티어 하위 요청 예산(호출당 약 50회): get_training_load_trend는 45일(기존 90일)로 제한, get_power_duration_curve는 활동 15개(기존 20개)로 제한, get_hrv_trend는 범위 엔드포인트를 한 번의 호출로 사용, 목표/걸음/월경 페이지네이션 루프는 상한이 적용됩니다.

• 도구는 사전 직렬화된 문자열 대신 JSON 객체를 반환하며, 오류는 MCP 도구 오류로 표시됩니다.

참고 사항

• Garmin 토큰은 Workers KV의 grant 내부에 암호화되어 저장됩니다. 만료(약 1년)되면 도구 호출이 실패하기 시작합니다. 클라이언트에서 서버를 다시 인증하여 흐름을 다시 실행하세요.

• 액세스 토큰은 베어러 자격 증명입니다. 유효한 토큰을 가진 사람은 누구든 만료될 때까지 데이터에 접근할 수 있으므로, 보안은 MCP 클라이언트가 저장된 토큰을 안전하게 유지하는 데 달려 있습니다.

• 로컬 개발: npm run dev를 실행한 후 클라이언트를 http://localhost:8787/mcp로 지정하세요.