igpsport-mcp

igpsport-mcp

英語 | 简体中文

iGPSport のサイクリングデータを Claude などの LLM クライアントに接続する、ローカルの MCP サーバーです。自然な言葉でトレーニングを分析できます。「今週のトレーニング負荷はどうですか？」 「先週と今週のロングライドを比較してください。」 「お気に入りに登録したあの坂での順位は？」 「今年は何キロ走りましたか？自己ベストも教えてください。」 — さらに、Claude にワークアウトを提案してもらうこともできます。「FTP に基づいて 2×20 SST セッションを作成して、サイクルコンピューターに送ってください。」

主な差別化ポイント：NP / IF / TSS / CTL / ATL / TSB などの派生トレーニング指標は、返却前にMCP レイヤーでサーバー側計算されます。LLM は生のストリームデータではなく、内容を説明しやすい数値を受け取ります。

You:   What's my training load trend over the last 90 days? Should I back off?
Claude (via analyze_training_load):
       Current CTL (Fitness) 72, ATL (Fatigue) 91, TSB (Form) -19 — you're in a significant fatigue hole.
       TSS has been above CTL for the past two weeks. Consider a 3–5 day recovery block to get TSB back above -5…

デモ

⚠️ 非公式プロジェクトです。このツールは、iGPSport のウェブクライアントのリクエストをシミュレートして動作します。iGPSport はいつでも API を変更する可能性があり、その場合、機能が動作しなくなることがあります。アカウントへのリスクはご自身で判断してください — 自己責任でご利用ください。すべてローカルで stdio 経由で動作し、お客様のデータがサードパーティーのサーバーに送信されることはありません。

クイックスタート（推奨）

このツールは MCP サーバーであり、MCP 対応クライアント（例：Claude Desktop / Claude Code / Cursor）が必要です。クライアントを準備したら、次の 3 つの手順を実行します。

1. uv をインストールします（スタンドアロンツールです。Python を事前にインストールする必要はありません。uv がランタイムを自動的に処理します）。

# macOS / Linux
curl -LsSf https://astral.sh/uv/install.sh | sh
# Windows (PowerShell)
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

2. グローバルにインストールし、セットアップウィザードを実行します（電話番号／メールアドレスとパスワードを対話形式で入力します。認証情報はローカルに保存されます）。コマンドはどちらのシステムでも同じです。macOS では Terminal、Windows では PowerShell で実行してください。

uv tool install igpsport-mcp
igpsport-mcp --setup

インストール後に igpsport-mcp が見つからない場合は、新しい Terminal／PowerShell ウィンドウを開いて PATH の更新を反映してください（uv は macOS では ~/.local/bin、Windows では %USERPROFILE%\.local\bin に実行ファイルを配置します）。

ウィザードは認証情報を設定ファイル（所有者のみ読み取り可能）に保存し、そのままコピーして貼り付けられる MCP 設定ブロックを表示します。設定ファイルの場所：

• macOS：~/.igpsport-mcp/config.json
• Windows：C:\Users\YourName\.igpsport-mcp\config.json

3. 表示された設定をクライアントに貼り付け、クライアントを再起動します（「Claude に接続する」を参照）。

貼り付ける前に認証情報を確認したい場合は、igpsport-mcp --check を実行してください。実際にログインして、✅ 成功または ❌ 失敗の理由を表示するため、クライアントに追加した後で動作しないと気づく事態を避けられます。

後で設定スニペットを再表示する必要がある場合は、いつでも igpsport-mcp --mcp-config を実行してください。

---

開発者や既存の Python 環境をお使いの方：単発実行には uvx igpsport-mcp を使用するか、ウィザードの代わりに以下の環境変数で設定してください。

CLI の使い方

引数なしで実行すると、stdio モードで MCP サーバーが起動します（MCP クライアントが実行するもので、通常は手動で実行しません）。その他のサブコマンド：

コマンド	目的
igpsport-mcp --setup	対話型セットアップウィザード：電話番号／メールアドレスとパスワードを入力し、ローカルの config.json に保存します
igpsport-mcp --mcp-config	そのままコピーして貼り付けられる MCP クライアント設定ブロックを表示します
igpsport-mcp --check	実際にログインして認証情報を確認します（アカウントはマスク表示されます）
igpsport-mcp --lang en|zh	出力言語を設定します（IGPSPORT_LANG 環境変数でも設定可能。デフォルトは zh）
igpsport-mcp --version	バージョン番号を表示します
igpsport-mcp --help	ヘルプを表示します

設定（環境変数）

--setup ウィザードを実行したユーザーは、このセクションをスキップできます。認証情報はすでに保存されています。以下のセクションは、環境変数を使いたいユーザーや、CI／複数の環境で認証情報を管理する必要があるユーザー向けです。環境変数は config.json より優先されます。

変数	必須	説明
IGPSPORT_USERNAME	✅	iGPSport アカウント（中国では電話番号、海外ではメールアドレス）
IGPSPORT_PASSWORD	✅	パスワード
IGPSPORT_REGION	任意	リージョン。デフォルトは cn（中国サーバー app.igpsport.cn）。海外のユーザーは intl（app.igpsport.com）を設定します
IGPSPORT_FTP	任意	ワット単位の機能的作業閾値パワー。空欄にすると iGPSport プロフィールから自動読み込みされます。上書きする場合に設定します
IGPSPORT_LTHR	任意	bpm 単位の乳酸閾値心拍数。心拍ゾーンと hrTSS のフォールバックに使用されます。こちらも iGPSport から自動読み込みされます。上書きする場合に設定します
IGPSPORT_LANG	任意	出力言語。zh（デフォルト）または en
IGPSPORT_CACHE_DIR	任意	キャッシュディレクトリ。デフォルトは ~/.cache/igpsport-mcp（macOS）／C:\Users\You\.cache\igpsport-mcp（Windows）です
IGPSPORT_LOG_LEVEL	任意	デフォルトは INFO

FTP／LTHR は、デフォルトで iGPSport のアスリートプロフィールから自動読み込みされます（体重と最大心拍数も同様）。そのため、通常は手動で設定する必要はありません。アプリに登録されている値とは異なる閾値を使いたい場合にのみ、環境変数を設定してください。iGPSport プロフィールにも FTP が設定されていない場合、IF／TSS／CTL／ATL／TSB は計算できません。iGPSport に FTP を追加するか、IGPSPORT_FTP を設定してください。

海外版のサポート

IGPSPORT_REGION=intl を設定すると、海外版（app.igpsport.com）に切り替わります。海外サーバーと中国サーバーではアカウントが別々です。app.igpsport.com で別途登録する必要があります。

中国サーバーとの違い：

• WASM 署名は不要です。認証には純粋な JWT を使用する、よりシンプルな設計です
• セグメント機能は利用できません（海外版のセグメントはベータ版で、一覧は空です）
• トレーニングパラメーターのエンドポイントは v2 パスを使用します。年間統計のパスも異なります（内部で自動適応）
• ワークアウトコースの形式はリージョンをまたいで互換性があるため、IR コンパイルレイヤーでの変更は不要です

設定例：

# via env vars
export IGPSPORT_REGION=intl
export [email protected]
export IGPSPORT_PASSWORD=your_password

または、--setup ウィザードの最初のステップで「2. International」を選択してください。

海外版の FIT ファイルは米国の OSS（oss-us-west-1）に保存されます。中国のユーザーはダウンロードに少し時間がかかる場合があります。

Claude に接続する

Claude Desktop

設定ファイル claude_desktop_config.json を開き（存在しない場合は作成し）、以下の内容を貼り付けてから、Claude Desktop を完全に終了して再起動してください。ファイルの場所：

• macOS：~/Library/Application Support/Claude/claude_desktop_config.json
• Windows：%APPDATA%\Claude\claude_desktop_config.json（つまり C:\Users\You\AppData\Roaming\Claude\claude_desktop_config.json）

Claude Desktop の Settings → Developer → Edit Config から、このファイルを直接開くこともできます。

--setup の実行後（認証情報は config.json に保存されています。env は空のままにしてください。これは --mcp-config が出力する設定です）：

{
  "mcpServers": {
    "igpsport": {
      "command": "igpsport-mcp",
      "args": [],
      "env": {}
    }
  }
}

または、ウィザードをスキップして、環境変数と uvx を使用します：

{
  "mcpServers": {
    "igpsport": {
      "command": "uvx",
      "args": ["igpsport-mcp"],
      "env": {
        "IGPSPORT_USERNAME": "your_phone_or_email",
        "IGPSPORT_PASSWORD": "your_password"
      }
    }
  }
}

FTP／LTHR はデフォルトで iGPSport プロフィールから自動読み込みされるため、設定する必要はありません。アプリに登録されている値を上書きしたい場合にのみ、env に "IGPSPORT_FTP": "250" または "IGPSPORT_LTHR": "160" を追加してください。

Claude Code

ウィザードの実行後（認証情報は保存されています）：

claude mcp add igpsport --scope user -- igpsport-mcp

または、uvx と環境変数を使用します：

claude mcp add igpsport --scope user \
  --env IGPSPORT_USERNAME=your_phone_or_email \
  --env IGPSPORT_PASSWORD=your_password \
  -- uvx igpsport-mcp

/mcp または claude mcp list で確認してください。ステータスが connected になっている必要があります。

OpenClaw

OpenClaw は、Claude Desktop／Claude Code と同じプロトコルである MCP の stdio を使用するため、上記の設定をそのまま利用できます。

方法 1：OpenClaw に自然言語で依頼する（推奨）

まず、uv tool install igpsport-mcp でインストールし、igpsport-mcp --setup を実行します。その後、接続済みのチャットチャンネルで、OpenClaw に次のように伝えるだけです。

igpsport-mcp をインストールしました。OpenClaw で設定できるよう手伝ってください。

OpenClaw がバイナリのパスを探し、igpsport-mcp --check で認証情報を確認し、openclaw mcp add を使って設定を書き込み、接続をテストします。コマンドラインや JSON を手動で操作する必要はありません。

方法 2：ワンライナー

# After the wizard (credentials stored)
openclaw mcp add igpsport --command igpsport-mcp

# Or with uvx + env vars
openclaw mcp add igpsport --command uvx --args igpsport-mcp \
  --env IGPSPORT_USERNAME=your_phone_or_email \
  --env IGPSPORT_PASSWORD=your_password

これは ~/.openclaw/openclaw.json の mcp.servers.igpsport に書き込みます。ファイルを手動で編集することもできます。

{
  mcp: {
    servers: {
      igpsport: {
        command: "igpsport-mcp",
        args: [],
        env: {}
      }
    }
  }
}

確認方法：

openclaw mcp list      # should show igpsport
openclaw mcp status    # igpsport: stdio
openclaw mcp probe     # igpsport: 17 tools, resources, prompts

mcp フィールドはホットリロードされるため、ゲートウェイの再起動は不要です。次の会話ターンから反映されます。必要に応じて、openclaw mcp reload を使ってランタイムキャッシュを強制的に更新してください。その後、接続済みの任意のチャンネル（Discord、Telegram、Slack など）から、自然言語で質問できます。

接続できませんか？ まずターミナルで igpsport-mcp --check を実行し、問題の箇所を特定してください。

• ❌ ログインに失敗する → 認証情報の問題です。igpsport-mcp --setup を再実行してください。

• ✅ 成功するのにクライアントが接続できない → igpsport-mcp／uvx がクライアントの PATH に含まれていない可能性があります（特に Claude Desktop は、ログインシェルの PATH を認識できないことがよくあります）。設定の command を絶対パスに置き換えてください。

• macOS：ターミナルで which igpsport-mcp（または which uvx）を実行します。例：/Users/You/.local/bin/igpsport-mcp

• Windows：PowerShell で where.exe igpsport-mcp（または where.exe uvx）を実行します。例：C:\Users\You\.local\bin\igpsport-mcp.exe。JSON では、バックスラッシュを二重にする必要があります。例："command": "C:\\Users\\You\\.local\\bin\\igpsport-mcp.exe"

アップデート

uv tool install でインストールした場合（どちらのシステムでも）、最新バージョンにアップグレードするには、次を実行します。

uv tool upgrade igpsport-mcp

アップグレード後にクライアントを再起動してください（Claude Desktop は完全に終了してから再度開き、Claude Code は再接続してください）。現在のバージョンを確認するには、igpsport-mcp --version を実行します。

uvx igpsport-mcp を単発で実行する場合、手動でのアップグレードは不要です。uvx はデフォルトで最新バージョンを使用します。古いバージョンがローカルにキャッシュされている場合は、uvx igpsport-mcp@latest を使うか、先に uv cache clean でキャッシュを削除してください。

アンインストール

1. プログラムを削除する（どちらのシステムでも同じです）。

uv tool uninstall igpsport-mcp

2. ローカルの認証情報とキャッシュを削除する（任意。完全にクリーンアップする場合）。

# macOS / Linux (Terminal)
rm -rf ~/.igpsport-mcp        # credentials (config.json)
rm -rf ~/.cache/igpsport-mcp  # tokens, SQLite, FIT file cache

# Windows (PowerShell)
Remove-Item -Recurse -Force "$env:USERPROFILE\.igpsport-mcp"
Remove-Item -Recurse -Force "$env:USERPROFILE\.cache\igpsport-mcp"

3. クライアントの設定から igpsport を削除する：Claude Desktop — claude_desktop_config.json の mcpServers にある igpsport ブロックを削除します。Claude Code — claude mcp remove igpsport を実行します。OpenClaw — openclaw mcp unset igpsport を実行するか、~/.openclaw/openclaw.json の mcp.servers にある igpsport ブロックを削除します。

uvx igpsport-mcp を単発で実行する場合、アンインストールする「プログラム」はありません。手順 2 と 3 のみ実行してください。

提供される17個のツール

アクティビティとトレーニング（9）

ツール	目的
list_activities	アクティビティを一覧表示します（日付範囲、ページネーションに対応）
get_activity_summary	単一アクティビティの派生指標：NP／IF／TSS／仕事量、心拍数およびパワーのゾーン滞在時間
get_activity_streams	時系列データ（ダウンサンプリングとチャンネル選択を強制適用し、トークンに配慮）
get_activity_laps	ラップ／セグメントデータ（ラップごとのNP）
get_athlete_profile	トレーニングパラメーター：FTP／LTHR（iGPSportから自動取得するか、環境変数で上書き可能）。体重と最大心拍数は常にiGPSportから取得し、ゾーン境界も含みます
get_athlete_stats	期間ごとに集計した統計（アクティビティ一覧からローカルで算出）
estimate_thresholds	公式テストを受けていないライダー向けに、最近のライドの平均最大曲線からFTP／LTHRを推定します（Cogganの20分テスト、クリティカルパワーとの相互検証、Frielのフィールド心拍数テスト）。各値には信頼度と根拠が付与され、「公式テストで確認してください」という注意書きが含まれます。読み取り専用です。書き戻しは行わず、ライダー自身が手動で適用します
compare_activities	複数のアクティビティ（2～5件）を比較します
analyze_training_load	CTL／ATL／TSBの傾向とコンディションの解釈を提示します（目玉となるクエリ）

セグメント（3）

ツール	目的
list_segments_collected	お気に入り登録したセグメントを自己ベストタイムとともに一覧表示します
get_segment_detail	セグメントの詳細：距離／勾配／獲得標高、KOM、リーダーボードの最速記録、自己PR
get_segment_rank	セグメントのリーダーボード（query_type は1＝全期間、2＝年間など）。自分の順位も含みます

統計と実績（1）

ツール	目的
get_member_statistics	公式の年間統計と自己ベスト：総距離／走行時間／消費カロリー／TSS、月間距離、距離の節目、各種PR（最長距離／最長時間／最速／最大パワー／最大標高）

トレーニングコース（4） — 唯一の「書き込み」機能

ツール	目的
create_workout	自然言語で構成されたトレーニングセッション（ウォームアップ／メインセット／インターバル／クールダウン）を記述すると、iGPSportのネイティブ形式に変換してサイクルコンピューターアプリに送信します。送信せずにプレビューする dry_run=true に対応し、with_calendar=true を指定すると、Apple Calendar、Reminders、Notionなどの後続ツール向けに標準のiCalendar（VEVENT）アーティファクトも返します
list_workouts	サーバーからカスタムワークアウトをリアルタイムで取得します（アプリで行った削除も反映されます）
get_workout_detail	特定のワークアウトの全構成を取得します
delete_workout	ワークアウトを削除します。破壊的で取り消し不能な操作です。デフォルトでは確認用のプレビューを表示し、実際に削除するには明示的に confirm=true を指定する必要があります

パワー目標には、絶対値のワット数、%FTP（FTPを使って自動換算）、パワーゾーンを指定できます。心拍数、ケイデンス、速度の目標にも対応しています。時間／距離／カロリー／手動ラップボタンで時間を設定できます。作成したワークアウトはiGPSportアプリの「トレーニングコース」に表示され、サイクルコンピューターに同期して実行できます。

派生指標リファレンス

• NP（ノーマライズドパワー）：((30 s rolling average power)^4 mean)^0.25。計算前にストリームを1 Hzに再サンプリングします。
• IF = NP / FTP、TSS = duration_s × NP × IF / (FTP × 3600) × 100。
• CTL／ATL／TSB：日次TSSの指数加重移動平均（α = 1/42、1/7）。TSB = CTL − ATL。
• パワーメーターがない場合の代替値：hrTSS = (duration_s / 3600) × (avg HR / LTHR)² × 100。estimated from HR と注記されます。
• ゾーンモデル：心拍数にはFriel（LTHRベース）、パワーにはCogganの7ゾーン（FTPベース）を使用します。

よくある質問

Q: パワーメーターは必要ですか？ A: いいえ。パワーメーターがなくても、心拍数ベースの指標は通常どおり機能し、TSS は hrTSS にフォールバックします（精度は低くなり、その旨が注記されます）。ただし、パワーベースの指標を利用するには、FTP を設定することをおすすめします。

Q: データはどこかにアップロードされますか？ A: サードパーティにはアップロードされません。ご自身の iGPSport アカウントデータの読み取り／書き込み（アクティビティ／統計の読み取り、およびご自身のトレーニングコースに対する create_workout／delete_workout）を除き、すべての処理はローカルで行われます。FIT ファイルと派生指標はローカルにキャッシュされます。

Q: create_workout／delete_workout によってデータが損なわれることはありますか？ A: create_workout は新しいトレーニングコースを追加するだけです。dry_run=true を使えば、送信を決める前にコンパイル結果をプレビューできます。delete_workout は取り消しできず、デフォルトでは確認用のプレビューが表示されます。実際に削除するには明示的に confirm=true を指定する必要があるため、LLM が確認なしにコースを削除することはありません。

Q: with_calendar は自動的にカレンダーに書き込みますか？ A: いいえ。このサーバーが生成するのは標準の iCalendar（VEVENT）テキストアーティファクトのみです。カレンダー API にアクセスしたり、外部にデータを送信したりすることはありません。イベントを実際にカレンダーに書き込むかどうかは、LLM クライアントが別のカレンダー／リマインダーツール（Apple Calendar、Reminders、Notion MCP など）に引き渡すかどうかによります。ワークアウトは実施日が指定されていないテンプレートのため、DTSTART はプレースホルダーの {{SCHEDULED_DATE}} です。後続の処理を行う側が実際の日付を設定します。

Q: API が動作しなくなった場合はどうなりますか？ A: iGPSport が API を変更すると、動作に支障が生じる可能性があります。その場合、ツールは明確なエラーを返します。Issues から問題を報告してください。

Q: ランニングや他のサイクルコンピューターにも対応していますか？ A: いいえ。このプロジェクトは iGPSport のサイクリングデータのみに対応しています。

Q: 国際版は何が異なりますか？ A: 国際版と中国版のサーバーアカウントは別々です。国際版にはセグメント機能がなく（ベータ版で、一覧は空です）、認証方式もよりシンプルです（WASM 署名は不要です）。アクティビティ、トレーニングコース、統計は同じように機能します。詳しくは「国際版のサポート」セクションをご覧ください。

開発

uv sync --extra dev
uv run pytest            # tests
uv run pytest -m integration   # online integration tests
ruff check . && ruff format .  # lint / format

ライセンス

MIT。このプロジェクトは iGPSport とは一切関係ありません。