Garmin Connect MCP server

Garmin Connect で筋力トレーニングを行うための MCP サーバーです。AI アシスタントとの会話でセッションを設計し、ウォッチにプッシュして、実際に挙げた重量を読み戻せます。

非公式。 Garmin とは提携、承認、サポートの関係はありません。 Garmin および Garmin Connect は Garmin Ltd. の商標です。このプロジェクトは リバースエンジニアリングされた python-garminconnect クライアントを通じて Garmin の非公開ワークアウトサービスエンドポイントにアクセスするため、 Garmin が予告なく変更・停止する可能性があります。 自己責任でご利用いただき、Garmin の利用規約に基づくご自身の義務も確認してください。

すべてローカルで動作します。認証情報はあなたのマシン上に留まり、送信されるのは Garmin のみです。

なぜ存在するのか

Garmin Connect はワークアウトの .FIT ファイルをインポートできません。FIT インポートは完了したアクティビティのみに対応しており、計画したワークアウトには対応していません。選択肢は、Connect の Web UI を手作業で操作するか、Web アプリ自身が呼んでいる非公開エンドポイントを使うかです。このプロジェクトは後者の方法を使い、そこに MCP インターフェースをかぶせています。これにより、20 分間のクリック作業の代わりに、会話からワークアウトが生まれるようになります。

ツール

破壊的なツールは delete_workout だけです。

セットアップ

Python 3.12 以降が必要です (garminconnect 0.3.x がそれを要求します)。

git clone https://github.com/YOUR-USERNAME/garmin-mcp.git
cd garmin-mcp
./setup.sh

setup.sh はプロジェクトディレクトリに .venv/ を作成し、依存パッケージをインストールし、.env.example を .env に変更します。システム全体にインストールはありません。お使いの新しい Python に依存パッケージの wheel がまだない場合は、上書き指定してください:

PYTHON=python3.13 ./setup.sh

.env に Garmin のログイン情報を記入し、一度だけ認証してください:

./.venv/bin/python garmin_login.py

このステップは意図的にインタラクティブです。Garmin が MFA コードを求めることがあり、MCP サーバにはそれを求めるターミナルがないため、フリーズしてしまうだけだからです。ログインはトークンを ~/.garminconnect にキャッシュし、以後サーバーはそのトークンを無言で再利用します。サーバーがセッションの失効を報告した場合にだけ、再実行してください。

ネットワークに触れずにビルドを検証する:

./.venv/bin/python garmin_mcp.py --self-test

クライアントに接続する

Claude Desktop

claude_desktop_config.json に追加します — macOS は ~/Library/Application Support/Claude/、Windows は %APPDATA%\Claude\ です:

{
  "mcpServers": {
    "garmin": {
      "command": "/absolute/path/to/garmin-mcp/.venv/bin/python",
      "args": ["/absolute/path/to/garmin-mcp/garmin_mcp.py"]
    }
  }
}

素の python ではなく、絶対パスと venv のインタープリタを使用してください — アプリはシェルの PATH を引き継ぎません。その後、アプリを再起動してください。

それ以外

標準的な stdio MCP サーバーのため、どのクライアントでも動作します。クライアントの外でデバッグするには:

npx @modelcontextprotocol/inspector ./.venv/bin/python garmin_mcp.py

プログラム

プログラムは programs/ 内の JSON ファイルで、複数日にまたがるテンプレートを記述します。sync_program はその中にあるすべてのワークアウトを名前で照合してプッシュします — 既存のワークアウトはその場で更新され、新しいものは作成されます。コメント付きテンプレートは programs/example.json を参照してください。

{
  "name": "Example Upper/Lower",
  "workouts": [
    {
      "name": "[EX] Upper A",
      "warmup": "Two or three ramp-up sets.",
      "blocks": [
        {
          "repeat": 4,
          "steps": [
            { "exercise": "Barbell Bench Press", "reps": 5, "weight_kg": 60,
              "note": "4x5-7. Add 2.5kg once you hit 7 on every set." },
            { "rest_seconds": 180 }
          ]
        }
      ]
    }
  ]
}

ブロック は、repeat の回数だけ繰り返されるグループです。ステップ は、エクササイズ (weight + reps、任意で weight_kg と note) か、休憩 (rest_seconds) のどちらかです。スーパーセットは、間に短い休憩と最後に長い休憩を持つ 1 つのブロックです。自重種目では weight_kg を省略します。デフォルトのウォームアップステップを使う場合は warmup を省略し、ウォームアップなしにする場合は warmup を "" にします。

programs/*.json は、サンプルを除いて gitignore されているため、あなた自身のトレーニングがコミットに紛れることはありません。

落とし穴

Garmin は認識できないエクササイズ名を静かに空欄にします。 アップロードは 200 を返し、その種目はセッション中、ウォッチに名前なしで表示されます。このため 捜索_exercises があり、アップロード前にすべての名前がカタログと照合されるのです。表示名は誰もタイプしないよう点でハイフン区切り — "Gaimに依存して下" など — なので、検索は句読点を正規化し、"db"、"bb" "ohp"、"rdl"、"skullcrusher" のような略語 も解釈します。

API の両側で重量単位が食い違っています。 ワークアウトサービスは、weightUnit が "factor": 1000.0 を持っているにもかかわらず、weightValue をキログラムで受け取ります。アクティビティのペイロード — すなわち、実際に挙げた重量 — はグラムで報告されます。どちらも対応済みなので、どちらを "修正" しないこと。

往復検証は単位のミスを検出できません。 これは Garmin が保存した値と送信した値を比較するだけであり、Garmin は送った値を忠実にも保存します。グラムを送っていたときも検証は成功し、Connect には "75,000 kg" と表示されていました。最初のアップロードは Connect で目視で確認してください。

削除して作り直すのではなく、更新してください。 ワークアウト ID を保つことウォッチが変更を "編集" として扱います。作り直すと、ウォッチは古いワークアウトを破棄して新しいものを取り込み直すため、古い重複が生まれます。

429 と 401 は見分けがつきません。 Garmin は IP ごとのログインを攻撃的にレート制限しています。最初のログイン経路が制限されると、garminconnect のフォールバックが紛らわしい 401 を報告します。直前に 429 を見ていたなら、それはスロットリングです — 30〜60 分待ってください。ブロック時間を延ばすため、ループで試し続けないでください。パスワードが本当に間違っていないかを切り分けるには: garmin_login.py --check-env。

レイアウト

garmin_mcp.py       the server — tool definitions
garmin_core.py      auth, payload building, verification, set parsing
garmin_login.py     one-time interactive login (MFA lives here)
programs/           multi-day templates as JSON
setup.sh            creates .venv and installs dependencies

ライセンス

MIT — LICENSE を参照。

python-garminconnect (MIT) と MCP Python SDK (MIT) を土台にしています。