Personal Garmin MCP

Garmin Connectで構造化ワークアウトを作成・スケジュールするためのローカルMCPサーバーです。非公式のGarminエンドポイントを使用します。

これは実験的な個人プロジェクトです。Garminは事前の通知なしにエンドポイントを変更したり、リクエストをレート制限したり、セッションを失効させたりする場合があります。別途認証を追加せずにサーバーをインターネットに公開しないでください。

機能

• 保存済みのGarminセッションを検証します；

• 変更を加えずにGarmin JSONをプレビューします；

• ワークアウトを作成し、オプションでカレンダーに追加します；

• ワークアウトライブラリとカレンダーを一覧表示します；

• 完了したアクティビティ、コンパクトなサマリー、ラップ/スプリット指標を読み取ります；

• 利用可能な睡眠、HRV、Body Battery、トレーニングレディネス、トレーニングステータスを読み取ります；

• ワークアウトを削除し、カレンダーからワークアウトを削除します；

• ランニング、サイクリング、ウォーキング、ハイキングに対応します；

• 時間、距離、lap buttonステップに対応します；

• インターバルリピートに対応します；

• ペース、心拍数、パワー、ケイデンスのターゲットに対応します；

• すべての変更にconfirm=trueが必要です。

Related MCP server: garmin-mcp

インストール

Docker Compose — 推奨

ローカルでの使用には、Compose対応のDockerが必要です。リポジトリのルートからイメージをビルドします：

docker compose build

ビルドでは、Pythonの依存関係をuvを使用してuv.lockからのみ厳密にインストールします。

対話型ログインを一度実行します。パスワードと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
          }
        ]
      }
    ]
  }
}

ペース値は1キロメートルあたりの秒数で指定します：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は、1つのアクティビティのプランニング指標を返します；

• get_activity_splitsは、コンパクトなラップとインターバルの指標を返します；

• get_recovery_statusは、1つの日付について利用可能な睡眠、HRV、Body Battery、トレーニングレディネス、トレーニングステータスを集約します。

アクティビティの応答は、意図的にGPS座標と所有者の詳細を省略しています。回復指標はGarminデバイス、アカウント、日付によって異なります。欠落しているソースは利用不可として返され、回復リクエスト全体を失敗させることはありません。

チェック

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

ユニットテストはGarminに接触せず、認証情報を必要としません。

重要な制限事項

• これは公式のGarminトレーニングAPIではありません。

• 頻繁なログインではHTTP 429応答を受け取る場合があります。保存済みのトークンを再利用してください。

• トークンはGarmin Connectへのアクセスを提供するため、パスワードと同様に保護する必要があります。

• 作成は成功したがスケジュールに失敗した場合、ツールはcreated_not_scheduledとworkout_idを返します。作成されたワークアウトはライブラリに残ります。

• 定期的に使用する前に、Garmin Connectと対象のウォッチモデルで簡単なワークアウトを1つテストしてください。