intervals-icu-mcp

Intervals.icu MCP サーバー

Intervals.icu と連携するための Model Context Protocol（MCP）サーバーです。Claude、ChatGPT、その他の LLM を通じて、トレーニングデータ、ウェルネス指標、パフォーマンス分析にアクセスできます。

元のプロジェクトは eddmann/intervals-icu-mcp（MIT ライセンス）に基づいています。このプロジェクトは、大幅なバグ修正と新機能を加えた独立した継続プロジェクトです。詳細は CHANGELOG.md をご覧ください。

概要

アクティビティ、アクティビティ分析、アクティビティメッセージ、アスリートプロフィール、ウェルネス、イベント／カレンダー、パフォーマンス曲線、ワークアウトライブラリ、ギア、スポーツ設定、カスタム項目にわたる69個のツールに加え、4つのMCPリソース（アスリートプロフィール、ワークアウト構文、イベントカテゴリ、カスタム項目スキーマ）と9つのMCPプロンプト（トレーニング分析、リカバリーチェック、週間計画など）を提供します。カテゴリごとの内訳は利用可能なツールをご覧ください。

クイックスタート

または、Claude Desktop なら30秒で設定できます。

1. APIキーとアスリートIDを取得します。
2. Claude Desktop の設定に以下を追加します。

{
  "mcpServers": {
    "intervals-icu": {
      "command": "uvx",
      "args": ["intervals-icu-mcp"],
      "env": {
        "INTERVALS_ICU_API_KEY": "your-api-key-here",
        "INTERVALS_ICU_ATHLETE_ID": "i123456"
      }
    }
  }
}

3. Claude を再起動して、*「過去7日間のアクティビティを見せてください。」*と尋ねます。

Claude Code、Cursor、ChatGPT を使う場合は、クライアントの設定をご覧ください。ソースから実行する場合や Docker を使う場合は、インストールとセットアップをご覧ください。

前提条件

uvをインストールしてください。Python、依存関係、実行を1つのツールで管理できます。macOS／Linux では curl -LsSf https://astral.sh/uv/install.sh | sh（または brew install uv。Homebrew は Intel Mac へのインストールを終了しています）、Windows では powershell -c "irm https://astral.sh/uv/install.ps1 | iex"を実行します。その後、uvxが Python とパッケージを自動的に取得します。MCP クライアントが uvxを見つけられない場合は、which uvxで表示されるフルパスを commandに設定してください。代替手段として Docker も利用できます。

Intervals.icu API キーの設定

インストールする前に、Intervals.icu の API キーを取得してください。

1. https://intervals.icu/settings → Developer → Create API Key に移動します。
2. キーをコピーし、プロフィール URL に記載されているアスリートID（形式：i123456）を控えます。

インストールとセットアップ

推奨セットアップを使用する場合、個別にインストールするものはありません。 uv に同梱されている uvx が、MCP クライアントから初めて起動された際に intervals-icu-mcp パッケージを自動的にダウンロードしてキャッシュします。クライアント設定の設定スニペットをクライアントに貼り付けるだけで完了です。

git clone https://github.com/hhopke/intervals-icu-mcp.git
cd intervals-icu-mcp
uv sync
uv run intervals-icu-mcp-auth  # interactive credential setup; or create .env manually:
#   INTERVALS_ICU_API_KEY=your_api_key_here
#   INTERVALS_ICU_ATHLETE_ID=i123456

docker build -t intervals-icu-mcp .

# Interactive credential setup (creates intervals-icu-mcp.env in the current directory):
touch intervals-icu-mcp.env  # pre-create the file so Docker mounts it as a file, not a dir
docker run -it --rm \
  -v "$(pwd)/intervals-icu-mcp.env:/app/.env" \
  --entrypoint= intervals-icu-mcp:latest \
  python -m intervals_icu_mcp.scripts.setup_auth

クライアント設定

このサーバーは stdio 経由で MCP と通信し、仕様に準拠したすべてのクライアントで動作します。クライアントをクリックして展開してください。クイックスタート（uvx）に従った場合は最初の設定ブロックを使用してください。上記のソースまたは Docker の別の方法を使用した場合は、同じ折りたたみセクション内の該当するバリエーションを使用してください。

{
  "mcpServers": {
    "intervals-icu": {
      "command": "uvx",
      "args": ["intervals-icu-mcp"],
      "env": {
        "INTERVALS_ICU_API_KEY": "your-api-key-here",
        "INTERVALS_ICU_ATHLETE_ID": "i123456"
      }
    }
  }
}

{
  "mcpServers": {
    "intervals-icu": {
      "command": "uv",
      "args": ["run", "--directory", "/ABSOLUTE/PATH/TO/intervals-icu-mcp", "intervals-icu-mcp"]
    }
  }
}

{
  "mcpServers": {
    "intervals-icu": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "-v", "/ABSOLUTE/PATH/TO/intervals-icu-mcp.env:/app/.env", "intervals-icu-mcp:latest"]
    }
  }
}

claude mcp add intervals-icu --scope user \
  --env INTERVALS_ICU_API_KEY=your-key \
  --env INTERVALS_ICU_ATHLETE_ID=i123456 \
  -- uvx intervals-icu-mcp

{
  "mcpServers": {
    "intervals-icu": {
      "command": "uvx",
      "args": ["intervals-icu-mcp"],
      "env": {
        "INTERVALS_ICU_API_KEY": "your-api-key-here",
        "INTERVALS_ICU_ATHLETE_ID": "i123456"
      }
    }
  }
}

使用方法

自然言語で Claude に依頼して、Intervals.icu のデータを操作できます。最初に試せるプロンプトをいくつか紹介します。

"Show me my activities from the last 30 days"
"Am I overtraining? Check my CTL, ATL, and TSB"
"How's my recovery this week? Show HRV and sleep trends"
"Create a sweet spot cycling workout for tomorrow"
"What's my 20-minute power and FTP?"

カテゴリ別のプロンプト例の全リストについては、docs/examples.mdをご覧ください。

利用可能なツール

69 個のツール、4 個のリソース、9 個のプロンプトテンプレートがあります。以下に概要を1行で示します。詳細はdocs/tools.mdをご覧ください。

削除セーフティモード

破壊的な操作を行うツールは、オプションの INTERVALS_ICU_DELETE_MODE 環境変数（safe / full / none、デフォルトは safe）によって制限されます。これはモデルがアクセスできないサーバー側の制御機構であり、登録されていないツールは呼び出せません。モードの一覧、レスポンスの形式、TZ バッファーの根拠については、docs/tools.mdをご覧ください。

リモートデプロイ（HTTP / SSE）

サーバーはデフォルトで stdio 経由で動作します。これは Claude Desktop、Claude Code、Cursor などのローカルクライアントに適したトランスポートです。リモートまたはホスト型での利用には、HTTP および SSE トランスポートを使用できます。

⚠️ MCP には認証機能が組み込まれていません。トンネル（Tailscale、Cloudflare Tunnel）または認証機能を持つリバースプロキシを使用せずに、HTTP モードのサーバーを信頼できないネットワークに公開しないでください。

トランスポートのフラグとセキュリティモデルの詳細については、docs/remote-deployment.mdをご覧ください。

ドキュメント

• プロンプト例 — カテゴリー別の自然言語プロンプトを網羅したカタログ
• ツールリファレンス — ツール、リソース、プロンプトの完全な一覧
• アーキテクチャ概要 — サーバー、ミドルウェア、クライアント、ツールの連携方法
• リモートデプロイ（HTTP/SSE） — ホスト型／リモート環境向けのトランスポート、フラグ、セキュリティモデル
• テストガイド — pytest + respx の規約、フィクスチャ、テストスイートの実行方法
• 変更履歴 — リリース履歴
• 新しいツールの追加 — コントリビューター向けの手順を追ったワークフロー

フィードバック

どのように使っていますか？ よく使うツール、プロンプトの内容、使いづらい点を教えてください。そうした声は、私自身の推測よりもロードマップの策定に大きく役立ちます。

使い方の紹介 · Q&A · アイデア · 一般 — または、再現可能なバグについてはイシューを作成してください。

コントリビューション

コントリビューションを歓迎します。小さなものでも大歓迎です — 誤字の修正、パラメーターの説明の改善、テストの追加、新しいツールの作成など、何でも歓迎します。Python や MCP の知識は必要ありません。CONTRIBUTING.mdをご覧ください。要約すると、PR を作成する前に make can-release を実行してください。初めての方におすすめのイシューから始めるのがおすすめです。

スポンサー

MIT License のもとで無料で利用でき、私が空き時間にメンテナンスしています。役に立った場合は、GitHub Sponsorsを通じて継続的な開発を支援できます。支援は完全に任意です。フィードバックや PR も同じように助けになります。

ライセンス

MIT License です。詳細はLICENSEファイルをご覧ください。

免責事項

このプロジェクトは Intervals.icu との提携、承認、スポンサー関係はありません。すべての製品名、ロゴ、ブランドは、それぞれの所有者に帰属します。