Garmin MCP

프로젝트 상태(2026-08-23): 개인 터널 구현, 로컬 스모크 테스트 통과. 친구 액세스나 공개 MCP 인그레이스(ingress)를 활성화하지 마세요. 실제 Garmin 자격 증명은 운영자가 별도의 공개 HTTPS link-web 터널을 명시적으로 승인하고 PERSONAL_TUNNEL_RUNBOOK.md의 실전 테스트 체크리스트를 완료하기 전까지는 차단된 상태로 유지됩니다.

다중 사용자, 읽기 전용 MCP 리소스 서버로 cyberjunky/python-garminconnect를 래핑합니다. MCP 도구 인자로 사용자 ID를 받지 않고 인증된 Garmin 데이터를 노출합니다.

보안 모델

아래 항목들은 원래 설계 의도를 설명합니다. 현재 구현으로 검증되지 않은 부분이 남아 있으며, 알려진 갭(gap)과 필수 인수 테스트 항목은 DESIGN_DRAFT.md에서 추적됩니다.

• MCP bearer 토큰은 Garmin 인증과 별도로 검증됩니다. 프로덕션 OIDC는 서명, 발급자(issuer), 대상(audience), 만료, 필수 스코프(scope)를 검증하고, 검증된 sub 클레임을 사용합니다.

• Garmin 이메일, 비밀번호, MFA 코드는 해당 요청 중에만 존재하며, 저장되거나 로깅되지 않습니다. Uvicorn 액세스 로깅은 비활성화되어 있습니다.

• python-garminconnect의 직렬화된 세션 JSON만 저장되며, AES-256-GCM으로 암호화되고 소유 주체(principal)에 대해 인증되므로 암호문(ciphertext)을 사용자 간에 옮길 수 없습니다.

• MFA 클라이언트는 프로세스 로컬(process-local)이고 일회용이며 소유자에 귀속되고, 5분 후 만료됩니다.

• 연결 URL은 서명된 일회용 상태를 프래그먼트(fragment)에 넣습니다. 외부 JavaScript가 프래그먼트를 지우고 상태를 POST 본문으로 옮겨, HTTP 및 프록시 액세스 로그에 남지 않게 합니다.

• 연결 해제는 로컬 암호화 토큰을 삭제합니다. 이는 Garmin이 이미 발급한 토큰을 취소하지는 않습니다. 토큰 손상이 의심된다면 Garmin 계정 보안 설정에서 액세스를 해지하세요.

Related MCP server: garmin-mcp

개인 ChatGPT 터널 모드

개인 구성은 의도적으로 두 개의 리스너(listener)를 사용합니다.

• SERVER_ROLE=mcp: 루프백 포트 3000에서 수신하며, 이 포트에는 OpenAI Secure MCP Tunnel만 접근할 수 있습니다.

• SERVER_ROLE=link-web: 루프백 포트 3001에서 수신하며, 별도의 HTTPS 터널은 이 리스너만 노출할 수 있습니다. 휴대폰은 MCP 엔드포인트를 노출하지 않고도 Garmin 자격 증명을 입력할 수 있습니다.

AUTH_MODE=tunnel에는 구성된 TUNNEL_PRINCIPAL_ID가 하나만 있으며, 다중 사용자 모드가 아닙니다. OpenAI 터널이 인증 경계이고, 서버는 컨테이너 격리가 명시적으로 활성화되지 않는한 결합 모드(combined mode)나 루프백 외부 바인드를 거부합니다. 전체 엔드투엔드 구성은 PERSONAL_TUNNEL_RUNBOOK.md을 참조하세요.

로컬 실행

Requirements: Python 3.12+, PostgreSQL 17, uv가 필요합니다.

cp .env.example .env
# Fill secrets, then for local-only bearer authentication set AUTH_MODE=development.
uv sync --all-extras
psql "$DATABASE_URL" -f migrations/001_initial.sql
uv run garmin-mcp

또는 .env 작성 후 docker compose up --build를 실행하세요. Compose는 두 애플리케이션 포트를 127.0.0.1에만 게시하며 PostgreSQL은게시하지 않습니다. MCP 엔드포인트는 /mcp, 헬스 엔드포인트는 /healthz입니다. 개발 모드에서는 bearer 값 자체가 로컬 사용자 ID입니다. 개발 모드를 루프백 밖으로 노출하지 마세요.

MCP 도구

• get_connection_status

• connect_garmin — 10분간 유효한 일회용 브라우저 URL을 반환합니다.

• get_profile

• disconnect_garmin

현재 Garmin 데이터 도구는 읽기 전용이며, disconnect_garmin은 저장된 세션을 삭제하는 것만으로 로컬 연결 상태를 변경합니다. 계정 자격 증명은 브라우저 연동 페이지에서만 입력할 수 있고, MCP 도구 인자로 제공되지 않습니다. 건강/활동 관련 도구는 아직 구현되지 않았습니다.

검증

uv run ruff check .
uv run mypy src
uv run pytest
uv build
uv run pip-audit

CI에 실제 Garmin 자격 증명을 넣지 마세요. 향후 실전 테스트에서는 전용 계정과 명시적인 integration-test 마커를 반드시 사용해야 합니다.