Intervals.icu MCP Server

Intervals.icu MCP サーバー

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

セットアップ

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. ［Settings］>［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_pzs8sxrjxfjjc\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 モードでサーバーを起動し、/sse と /messages/ エンドポイントを公開します。

   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
   • 認証：トンネルを保護していない場合は、認証なし のままにします。

   ここでも同じ ngrok http 8765 のトンネル 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

デバッグログの有効化

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

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