개인 Garmin MCP

Garmin Connect에서 구조화된 운동을 생성하고 일정을 예약하기 위한 로컬 MCP 서버로, 비공식 Garmin 엔드포인트를 사용합니다.

이는 실험적인 개인 프로젝트입니다. Garmin은 엔드포인트를 변경하거나 요청을 속도 제한하거나 세션을 사전 통지 없이 해지할 수 있습니다. 별도의 인증을 추가하지 않고 서버를 인터넷에 노출하지 마십시오.

기능

• 저장된 Garmin 세션을 검증합니다;

• 변경 없이 Garmin JSON을 미리 봅니다;

• 운동을 생성하고 선택적으로 캘린더에 추가합니다;

• 운동 라이브러리와 캘린더를 나열합니다;

• 완료된 활동, 간결한 요약, 랩/구간 지표를 읽습니다;

• 사용 가능한 수면, HRV, Body Battery, Training Readiness, Training Status를 읽습니다;

• 운동을 삭제하고 캘린더에서 운동을 제거합니다;

• 달리기, 사이클링, 걷기, 하이킹을 지원합니다;

• 시간, 거리, lap button 단계를 지원합니다;

• 인터벌 반복을 지원합니다;

• 페이스, 심박수, 파워, 케이던스 목표를 지원합니다;

• 모든 변경에는 confirm=true가 필요합니다.

Related MCP server: garmin-mcp

설치

Docker Compose — 권장

로컬 사용에는 Compose 지원이 포함된 Docker가 필요합니다. 저장소 루트에서 이미지를 빌드하세요:

docker compose build

빌드는 uv.lock에서 uv로 Python 의존성을 엄격하게 설치합니다.

대화형 로그인을 한 번 실행하세요. 비밀번호와 MFA 코드는 컨테이너에 직접 입력되며 저장되지 않습니다. OAuth 토큰은 개인 garmin-mcp_garmin_tokens 명명된 볼륨에 저장됩니다:

docker compose --profile login run --rm garmin-login

MCP 서버를 시작하세요:

docker compose up -d garmin-mcp
docker compose ps

엔드포인트는 http://127.0.0.1:8000/mcp에서 사용할 수 있습니다. 다른 로컬 포트를 사용하려면:

GARMIN_MCP_PORT=8765 docker compose up -d garmin-mcp

로그를 보거나 서버를 중지하세요:

docker compose logs -f garmin-mcp
docker compose down

docker compose down은 Garmin 토큰을 보존합니다. docker compose down -v를 실행하면 볼륨과 토큰이 삭제됩니다.

Docker 없이 로컬 설치

Python 3.12+ 및 uv가 필요합니다.

cd /path/to/garmin-mcp
uv sync --extra dev

일회성 로그인

uv run garmin-mcp-login

스크립트는 필요할 때 이메일 주소, 비밀번호, MFA 코드를 대화형으로 요청합니다. 비밀번호는 저장되지 않습니다. OAuth 토큰은 제한된 권한으로 .garmin-tokens/garmin_tokens.json에 저장됩니다. 해당 디렉터리는 이미 .gitignore에 포함되어 있습니다.

토큰을 다른 위치에 저장하려면:

export GARMIN_TOKEN_DIR=/safe/private/path/garmin-tokens
uv run garmin-mcp-login

stdio를 통한 로컬 MCP

export GARMIN_TOKEN_DIR=/safe/private/path/garmin-tokens
uv run garmin-mcp

MCP 클라이언트 구성 예시:

{
  "mcpServers": {
    "garmin": {
      "command": "/absolute/path/to/garmin-mcp/.venv/bin/garmin-mcp",
      "env": {
        "GARMIN_TOKEN_DIR": "/safe/private/path/garmin-tokens"
      }
    }
  }
}

ChatGPT용 Streamable HTTP

export GARMIN_MCP_TRANSPORT=streamable-http
export GARMIN_MCP_HOST=127.0.0.1
export GARMIN_MCP_PORT=8000
export GARMIN_TOKEN_DIR=/safe/private/path/garmin-tokens
uv run garmin-mcp

엔드포인트: http://127.0.0.1:8000/mcp.

ChatGPT는 HTTPS를 통해 엔드포인트에 도달할 수 있어야 합니다. 개인 테스트를 위해 보호된 터널을 사용할 수 있습니다. 이 MVP를 인터넷에 직접 노출하지 마십시오: 의도적으로 MCP 서버 자체에 대한 액세스를 위한 별도의 OAuth 리소스 서버를 포함하지 않습니다.

preview_workout 인자 예시

{
  "workout": {
    "name": "6 x 800",
    "sport": "running",
    "description": "Controlled intervals",
    "blocks": [
      {
        "steps": [
          {
            "step_type": "warmup",
            "duration_type": "time",
            "duration_value": 900
          }
        ]
      },
      {
        "repeat": 6,
        "steps": [
          {
            "step_type": "interval",
            "duration_type": "distance",
            "duration_value": 800,
            "target_type": "pace_seconds_per_km",
            "target_low": 250,
            "target_high": 260
          },
          {
            "step_type": "recovery",
            "duration_type": "time",
            "duration_value": 120
          }
        ]
      },
      {
        "steps": [
          {
            "step_type": "cooldown",
            "duration_type": "time",
            "duration_value": 600
          }
        ]
      }
    ]
  }
}

페이스 값은 킬로미터당 초 단위로 지정됩니다: 250 = 4:10/km, 260 = 4:20/km. 서버는 이를 Garmin Connect에서 사용하는 m/s 값으로 변환합니다.

미리 본 후, 동일한 객체, YYYY-MM-DD 형식의 날짜, confirm=true를 사용하여 create_workout을 호출하세요.

읽기 전용 훈련 컨텍스트

서버는 완료된 작업에 맞춰 향후 계획을 조정하기 위한 간결한 읽기 전용 도구를 제공합니다:

• list_activities는 포함된 날짜 범위의 활동을 나열하며, 선택적 Garmin 활동 유형 필터가 있습니다;

• get_activity_summary는 하나의 활동에 대한 계획 지표를 반환합니다;

• get_activity_splits는 간결한 랩 및 인터벌 지표를 반환합니다;

• get_recovery_status는 한 날짜에 대한 사용 가능한 수면, HRV, Body Battery, Training Readiness, Training Status를 집계합니다.

활동 응답은 의도적으로 GPS 좌표와 소유자 세부 정보를 생략합니다. 회복 지표는 Garmin 기기, 계정, 날짜에 따라 다릅니다. 누락된 소스는 사용 불가로 반환되며 전체 회복 요청이 실패하지 않습니다.

검사

uv run --extra dev pytest
uv run --extra dev ruff check .

단위 테스트는 Garmin에 연결하지 않으며 자격 증명이 필요하지 않습니다.

중요한 제한 사항

• 이는 공식 Garmin Training API가 아닙니다.

• 빈번한 로그인은 HTTP 429 응답을 받을 수 있습니다; 저장된 토큰을 재사용하세요.

• 토큰은 Garmin Connect에 대한 액세스를 제공하며 비밀번호처럼 보호해야 합니다.

• 생성은 성공했지만 일정 예약이 실패하면 도구는 created_not_scheduled 및 workout_id를 반환합니다; 생성된 운동은 라이브러리에 남아 있습니다.

• 정기적으로 사용하기 전에 Garmin Connect와 특정 시계 모델에서 간단한 운동 하나를 테스트하세요.