Garmin 읽기 전용 MCP

Hermes Agent와 함께 로컬에서 사용하기 위해 의도적으로 범위를 좁힌 Garmin Connect 통합 도구입니다. 선택한 Garmin 요약 정보를 소유자 전용 SQLite 캐시로 동기화한 후, 세 개의 읽기 전용 MCP 도구를 통해 정규화된 캐시만 제공합니다.

이 프로젝트는 커뮤니티에서 유지 관리하는 python-garminconnect 클라이언트와 문서화되지 않은 Garmin Connect 엔드포인트를 사용합니다. Garmin과 제휴 관계가 없으며 Garmin의 지원을 받지 않습니다. 엔드포인트는 변경될 수 있으며, 자동화된 접근은 계정 또는 이용약관 위험을 초래할 수 있습니다. 승인된 비즈니스 통합을 위해서는 공식 Garmin Connect 개발자 프로그램을 이용하는 것이 권장됩니다.

보안 모델

설계상 네트워크 접근과 MCP 프로세스를 분리합니다:

1. garmin-readonly-auth는 로컬 터미널에서 일회성 대화형 로그인을 수행합니다. 비밀번호와 MFA 입력은 숨겨지며 명령 인수로 절대 허용되지 않습니다.

2. garmin-readonly-sync는 재사용 가능한 로컬 세션 자료를 로드하고, 제한된 날짜 범위를 가져오며, 업스트림 필드를 제거하고 정규화된 요약 정보를 SQLite에 기록합니다.

3. garmin-readonly-mcp는 Garmin 클라이언트나 세션 자료를 가져오지 않습니다. 정규화된 SQLite 캐시만 읽으며, 심볼릭 링크, 일반 파일이 아닌 경우, 현재 사용자 소유가 아닌 경우, 또는 그룹/다른 사용자가 접근 가능한 캐시를 거부합니다.

기본 상태 디렉터리는 다음과 같습니다:

~/.local/share/garmin-readonly-mcp/
├── tokens/          # Garmin session material, mode 0700/0600
└── cache.sqlite3    # normalized cache, mode 0600

다른 루트를 사용하려면 비밀 정보가 아닌 GARMIN_READONLY_HOME 환경 변수를 설정하세요. 상태 디렉터리를 저장소 내부에 절대 배치하지 마세요.

Related MCP server: garmin-mcp-local

데이터 범위

캐시와 MCP는 다음만 노출합니다:

• 일일 총 칼로리, 활동 칼로리, BMR/기초 대사 칼로리

• 가능한 경우 걸음 수 및 안정 시 심박수

• 활동 유형, 시작 시간, 지속 시간, 거리 및 칼로리

• 가능한 경우 수면 시간/점수, Body Battery, 야간 HRV/상태 및 훈련 준비도

다음은 의도적으로 제외됩니다:

• Garmin 프로필 및 소셜 데이터

• 계정 식별자 및 활동 ID

• 기기 세부 정보

• GPS 좌표, 경로 및 FIT/GPX/TCX 파일

• 체중 및 체성분

• 원시 Garmin 응답

• 업로드, 업데이트, 예약 또는 삭제 작업

• 일반적이거나 임의적인 Garmin API 접근

Garmin 칼로리 값은 활동 맥락일 뿐이며, 음식 섭취를 늘리라는 명령이 아닙니다.

요구 사항

• 개인 파일 권한이 있는 Linux 또는 기타 Unix 계열 환경

• Python 3.12+

• uv

• Garmin Connect 계정

설치

git clone https://github.com/alexpomsft/garmin-readonly-mcp.git
cd garmin-readonly-mcp
uv sync --frozen

로컬 인증

Telegram, 채팅, 셸 기록 또는 공유 화면이 아닌 개인 로컬 터미널에서 실행하세요:

uv run garmin-readonly-auth

명령어는 로컬에서 이메일, 숨겨진 비밀번호, 그리고 Garmin이 요구하는 경우 숨겨진 MFA를 입력받습니다. 재사용 가능한 세션 자료를 저장하지만 비밀번호는 저장하지 않습니다.

동기화

기본값은 오늘과 어제를 동기화합니다:

uv run garmin-readonly-sync

제한된 과거 기간을 요청할 수 있습니다:

uv run garmin-readonly-sync --end-date 2026-08-18 --days 14

--days는 1에서 31 사이여야 합니다. 제공자 오류는 고정된 공개 메시지로 대체되므로 원시 Garmin 응답과 인증 세부 정보가 노출되지 않습니다.

MCP 서버 실행

최소 한 번의 성공적인 동기화 후:

uv run garmin-readonly-mcp

stdio 서버는 정확히 다음을 노출합니다:

• get_daily_activity(date: YYYY-MM-DD)

• get_recent_activities(days: 1..31 = 7)

• get_recovery_summary(date: YYYY-MM-DD)

도구 스키마는 선언되지 않은 인수를 거부합니다.

Hermes Agent에 연결

config.yaml을 수동으로 편집하는 대신 Hermes의 MCP 명령어를 사용하세요:

hermes mcp add garmin-readonly \
  --command /absolute/path/to/garmin-readonly-mcp/.venv/bin/garmin-readonly-mcp
hermes mcp test garmin-readonly

서버를 추가한 후 Hermes를 다시 시작하면 도구가 검색됩니다. MCP 구성에 자격 증명이나 세션 토큰 경로가 전달되지 않으며, 개인 기본 상태 루트를 사용합니다. GARMIN_READONLY_HOME이 사용자 지정된 경우, hermes mcp add ... --env GARMIN_READONLY_HOME=/private/path로 비밀 정보가 아닌 해당 설정만 전달하세요.

개발 및 검증

uv sync --frozen
uv run pytest --cov=garmin_readonly_mcp --cov-report=term-missing
uv run ruff check .
uv run mypy src tests
uv run pip-audit

구현은 먼저 실패하는 테스트로 개발되었습니다. CI는 동일한 테스트, 린트, 타입 검사 및 의존성 감사 게이트를 실행합니다.

제한 사항

• Garmin Connect 엔드포인트는 역공학된 것이며 사전 통지 없이 중단될 수 있습니다.

• Garmin은 자동화된 클라이언트에 속도 제한, 차단 또는 잠금을 적용할 수 있습니다.

• 일부 복구 필드는 특정 기기나 날짜에서 사용할 수 없으며 null을 반환합니다.

• 로컬 캐시는 스냅샷입니다. 더 최신 데이터가 필요하면 garmin-readonly-sync를 별도로 예약하세요.

• 이 프로젝트는 칼로리 목표를 자동으로 수정하거나 의학적 조언을 제공하지 않습니다.

자격 증명 처리 및 취약점 보고는 SECURITY.md를 참조하세요.