Intervals.icu MCP Server

Claude と ChatGPT を Intervals.icu API に接続するための Model Context Protocol (MCP) サーバーです。アクティビティ、アスリートプロフィール、ウェルネスデータ、パワーカーブ、カスタム項目の認証とデータ取得のためのツールを提供します。

この Model Context Protocol (MCP) サーバーが役立つと思われた場合は、継続的な開発をサポートするための寄付をご検討ください。

要件

• Python 3.12 以降

• Model Context Protocol (MCP) Python SDK

• httpx

• python-dotenv

Related MCP server: Intervals.icu MCP Server

セットアップ

1. uv のインストール(推奨)

macOS/Linux:

curl -LsSf https://astral.sh/uv/install.sh | sh

Windows (PowerShell):

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

インストール後、uv のフルパスを確認してください。この後、Claude Desktop を設定する際に必要になります:

where.exe uv
# Example output: C:\Users\<USERNAME>\.local\bin\uv.exe

2. このリポジトリをクローンする

git clone https://github.com/mvilanova/intervals-mcp-server.git
cd intervals-mcp-server

3. 仮想環境を作成して有効化する

# Create virtual environment with Python 3.12
uv venv --python 3.12

# Activate virtual environment
# On macOS/Linux:
source .venv/bin/activate
# On Windows:
.venv\Scripts\activate

4. プロジェクトの依存関係を同期する

uv sync

5. 環境変数を設定する

以下のコマンドを実行して、.env.example をコピーし、.env という名前を付けます:

macOS/Linux:

cp .env.example .env

Windows (PowerShell):

Copy-Item .env.example .env

次に、.env ファイルを編集して、Intervals.icu のアスリートID と APIキーを設定します:

API_KEY=your_intervals_api_key_here
ATHLETE_ID=your_athlete_id_here

Intervals.icu API キーの取得

1. Intervals.icu アカウントにログインします

2. 設定 > API に移動します

3. 新しい API キーを生成します

アスリート ID の確認

アスリート ID は、Intervals.icu にログインしているときの URL に通常表示されます。次のようになります:

• https://intervals.icu/athlete/i12345/... の i12345 がアスリート ID です

更新

このプロジェクトは積極的に開発されており、新しい機能や修正が定期的に追加されています。最新の状態に保つには、次の手順を実行します:

1. main ブランチの最新の変更をプルする

⚠️ このコマンドを実行する前に、未コミットの変更がないことを確認してください。

macOS/Linux:

git checkout main && git pull

Windows (PowerShell):

git checkout main; git pull

2. Python の依存関係を更新する

仮想環境を有効化し、依存関係を同期します:

macOS/Linux:

source .venv/bin/activate
uv sync

Windows (PowerShell):

.venv\Scripts\activate
uv sync

トラブルシューティング

設定の変更が原因で Claude Desktop が起動に失敗する場合は、次の手順に従ってください:

1. claude_desktop_config.json 内の既存の Intervals.icu エントリを削除します。

2. intervals-mcp-server ディレクトリから Claude Desktop を再設定します。

macOS/Linux:

mcp install src/intervals_mcp_server/server.py --name "Intervals.icu" --with-editable . --env-file .env

Windows: Windows の設定セクション の説明に従って、エントリを手動で追加し直してください。

よくあるエラー

spawn uv ENOENT — Claude Desktop が uv 実行ファイルを見つけられません。command フィールドに uv のフルパスを指定してください。フルパスを取得するには、which uv(macOS/Linux)または where.exe uv(Windows)を実行します。

Windows での spawn /Users/... ENOENT — 設定ファイルに macOS/Linux 形式のパスが含まれています。後述の Windows の設定セクション の説明に従って、バックスラッシュを使用した正しい Windows パスに置き換えてください。

Windows Store インストール: 設定変更が反映されない — 間違った設定ファイルを編集している可能性があります。Microsoft Store からインストールされた Claude Desktop は、AppData\Roaming\Claude\ ではなく、AppData\Local\Packages\Claude_pzsjx5b4mhj6x4\LocalCache\Roaming\Claude\claude_desktop_config.json から設定を読み取ります。

Claude での利用

1. Claude Desktop を設定する

このサーバーを Claude Desktop で使用するには、Claude Desktop の設定に追加する必要があります。

macOS/Linux

1. intervals-mcp-server ディレクトリで次のコマンドを実行して、Claude Desktop を設定します:

mcp install src/intervals_mcp_server/server.py --name "Intervals.icu" --with-editable . --env-file .env

2. Claude Desktop アプリの設定ファイル claude_desktop_config.json を開くと、次のようになっているはずです:

{
  "mcpServers": {
    "Intervals.icu": {
      "command": "/Users/<USERNAME>/.local/bin/uv",
      "args": [
        "run",
        "--with",
        "mcp[cli]",
        "--with-editable",
        "/path/to/intervals-mcp-server",
        "mcp",
        "run",
        "/path/to/intervals-mcp-server/src/intervals_mcp_server/server.py"
      ],
      "env": {
        "INTERVALS_API_BASE_URL": "https://intervals.icu/api/v1",
        "ATHLETE_ID": "<YOUR_ATHLETE_ID>",
        "API_KEY": "<YOUR_API_KEY>",
        "LOG_LEVEL": "INFO"
      }
    }
  }
}

ここで /path/to/ は、システム上の intervals-mcp-server コードフォルダーへのパスです。

Windows

mcp install コマンドは、Windows では環境または権限の問題により失敗する可能性があります。その場合は、Claude Desktop を手動で設定してください:

1. Claude Desktop の設定ファイルを探します。Claude Desktop が Microsoft Store からインストールされた場合、設定ファイルは次の場所にあります:

   C:\Users\<USERNAME>\AppData\Local\Packages\Claude_pzs8sxrjxfjjc\LocalCache\Roaming\Claude\claude_desktop_config.json

   標準のインストーラーでインストールされた場合、次の場所にある可能性があります:

   C:\Users\<USERNAME>\AppData\Roaming\Claude\claude_desktop_config.json

   ファイルまたはフォルダーが存在しない場合は作成します。

2. claude_desktop_config.json に次のエントリを追加し、プレースホルダーを実際の値に置き換えます:

{
  "mcpServers": {
    "Intervals.icu": {
      "command": "C:\\Users\\<USERNAME>\\.local\\bin\\uv.exe",
      "args": [
        "run",
        "--with",
        "mcp[cli]",
        "--with-editable",
        "C:\\path\\to\\intervals-mcp-server",
        "mcp",
        "run",
        "C:\\path\\to\\intervals-mcp-server\\src\\intervals_mcp_server\\server.py"
      ],
      "env": {
        "INTERVALS_API_BASE_URL": "https://intervals.icu/api/v1",
        "ATHLETE_ID": "<YOUR_ATHLETE_ID>",
        "API_KEY": "<YOUR_API_KEY>",
        "LOG_LEVEL": "INFO"
      }
    }
  }
}

• JSON 内の Windows のパスには、必ず二重バックスラッシュ(\\)を使用します。

• uv.exe のフルパスを確認するには、PowerShell で where.exe uv を実行します。

• クローンしたリポジトリのフルパスを確認するには、intervals-mcp-server フォルダー内で pwd を実行します。

Windows Store インストールの注意: Microsoft Store からインストールされた Claude Desktop は、設定を AppData\Local\Packages\... 配下にサンドボックス化します。AppData\Roaming\Claude\claude_desktop_config.json を編集しても反映されないため、正しいファイルを編集するようにしてください。

3. Claude Desktop を再起動します。

2. Claude で MCP サーバーを使用する

サーバーが起動し、Claude Desktop が設定されると、次のツールを使用して、過去および今後のアクティビティ、イベント、ウェルネスデータについて質問できます。

• get_activities: アクティビティのリストを取得します

• get_activity_details: 特定のアクティビティの詳細情報を取得します

• get_activity_intervals: 特定のアクティビティの詳細なインターバルデータを取得します

• get_activity_streams: 特定のアクティビティの生データストリーム(パワー、心拍数など)を取得します

• get_athlete_power_curves: 選択した期間および時間帯のベストパワー出力曲線を取得します

• get_wellness_data: ウェルネスデータを取得します

• get_events: 今後のイベント(ワークアウト、レースなど)を取得します

• get_event_by_id: 特定のイベントの詳細情報を取得します

• add_or_update_event: イベント(ワークアウト、レース、メモなど)を作成または更新します

• delete_event: 特定のイベントを削除します

• delete_events_by_date_range: 日付範囲内のイベントを削除します

• get_custom_items: アスリートのカスタム項目(チャート、カスタムフィールド、ゾーンなど)を取得します

• get_custom_item_by_id: 特定のカスタム項目の詳細情報を取得します

• create_custom_item: アスリートに新しいカスタム項目を作成します

• update_custom_item: 既存のカスタム項目を更新します

• delete_custom_item: カスタム項目を削除します

ChatGPT での利用

ChatGPT のベータ版 MCP コネクタは、SSE トランスポートを介してこのサーバーと通信することもできます。

1. /sse と /messages/ エンドポイントを公開するために、SSE モードでサーバーを起動します:

   export FASTMCP_HOST=127.0.0.1 FASTMCP_PORT=8765 MCP_TRANSPORT=sse FASTMCP_LOG_LEVEL=INFO
   python src/intervals_mcp_server/server.py

   起動ログには完全な URL(例: http://127.0.0.1:8765/sse)が表示されます。ChatGPT にはその公開 URL が必要なため、サーバーを直接公開していない場合は、ngrok http 8765 などのツールでポートを転送してください。

2. ChatGPT で 設定 → 機能 → カスタム MCP コネクタ を開き、追加 をクリックします。次の項目を入力します:

   • 名前: Intervals.icu

   • MCP サーバー URL: https://<your-public-host>/sse

   • 認証: トンネルを保護していない限り、認証なし のままにします。

   ここでも同じ cs.studio のトンネル URL を使用できます。ただし、上記でエクスポートしたホスト/ポートに転送されていることを確認してください。

3. コネクタを保存し、新しいチャットを開きます。ChatGPT は SSE 接続を開いたままにし、フォローアップリクエストをサーバーが通知する /messages/ エンドポイントに POST します。MCP サーバーまたはトンネルを再起動した場合は、SSE コマンドを再実行し、URL が変更されたらコネクタの URL を更新してください。

開発とテスト

開発依存関係をインストールし、次のコマンドでテストスイートを実行します:

uv sync --all-extras
pytest -v tests

サーバーをローカルで実行する

サーバーを手動で起動するには(開発中やテスト時に便利)、次のコマンドを実行します:

mcp run src/intervals_mcp_server/server.py

デバッグログの有効化

デバッグ用にサーバーログを取得するには、コマンドをシェルでラップし、stderr をファイルにリダイレクトします。

macOS/Linux — claude_desktop_config.json を次のように変更します:

{
  "mcpServers": {
    "Intervals.icu": {
      "command": "/bin/bash",
      "args": [
        "-c",
        "/Users/<USERNAME>/.local/bin/uv run --with 'mcp[cli]' --with-editable /path/to/intervals-mcp-server mcp run /path/to/intervals-mcp-server/src/intervals_mcp_server/server.py 2>> /path/to/intervals-mcp-server/mcp-server.log"
      ],
      "env": {
        "INTERVALS_API_BASE_URL": "https://intervals.icu/api/v1",
        "ATHLETE_ID": "<YOUR_ATHLETE_ID>",
        "API_KEY": "<YOUR_API_KEY>",
        "LOG_LEVEL": "INFO"
      }
    }
  }
}

次に、ログファイルを tail して、リアルタイムに出力を確認します:

tail -f /path/to/intervals-mcp-server/mcp-server.log

Windows — claude_desktop_config.json を次のように変更します:

{
  "mcpServers": {
    "Intervals.icu": {
      "command": "powershell",
      "args": [
        "-Command",
        "C:\\Users\\<USERNAME>\\.local\\bin\\uv.exe run --with 'mcp[cli]' --with-editable C:\\path\\to\\intervals-mcp-server mcp run C:\\path\\to\\intervals-mcp-server\\src\\intervals_mcp_server\\server.py 2>> C:\\path\\to\\intervals-mcp-server\\mcp-server.log"
      ],
      "env": {
        "INTERVALS_API_BASE_URL": "https://intervals.icu/api/v1",
        "ATHLETE_ID": "<YOUR_ATHLETE_ID>",
        "API_KEY": "<YOUR_API_KEY>",
        "LOG_LEVEL": "INFO"
      }
    }
  }
}

次に、PowerShell を使用してログファイルをリアルタイムで監視します:

Get-Content C:\path\to\intervals-mcp-server\mcp-server.log -Wait

ライセンス

GNU General Public License v3.0

注目

Glama.ai