ローカルVS CodeからKaggle GPUを操る：Claude Code連携で加速するKaggleワークフロー
タグ
Kaggle VSCode ClaudeCode Python 機械学習
はじめに
Kaggleのコンペに取り組む上で、ずっとネックになっていたのが開発環境の分断だ。KaggleのNotebook UIは実行環境としては申し分ないが、コード補完や差分管理、Claude Codeとの連携を考えると、手元のVS Codeで作業したい場面が多い。
そんな中、KaggleがVS Code（およびCursor）からJupyter Serverに直接接続できる機能を提供していることを知った。さらにKaggle APIを組み合わせることで、ローカルで編集・Kaggleで実行という理想的なワークフローが実現できたので、その手順を備忘録としてまとめておく。
仕組み：VS CodeからKaggle Jupyter Serverに接続する
KaggleはNotebookセッションに対して「VSCode Compatible URL」を発行する機能を持っている。このURLをVS CodeのJupyter拡張機能に登録することで、ローカルのVS CodeからKaggleのGPUカーネル上でコードを実行できる。
ローカルVS Code（編集・Claude Code連携）
↓ VSCode Compatible URL
Kaggle Jupyter Server（GPU実行）
↓
実行結果がVS Codeに返ってくる
重要なのは、Notebookファイル（.ipynb）はローカルに保存される点だ。Kaggle側はあくまでも実行エンジンとして機能する。
想定するユースケース
主に以下の2パターンで活用している。
① 他人のカーネルをベースに改造する
Kaggle上で公開されているカーネルを「Copy & Edit」して自分のカーネルとしてコピーし、それをKaggle API経由でローカルにpullして編集するフロー。ゼロから書くよりも、上位解法のコードを理解しながら手を加えていく使い方に適している。
② ローカルでClaude Codeと協調しながら開発する
手元のVS CodeにClaude Codeが入っているため、コード生成・デバッグ・リファクタリングをAIと会話しながら進め、実行だけKaggle GPUに委ねる。GPU環境を持たないローカルマシンでもリッチな開発体験が得られる。
全体の流れ
1. 事前準備：Kaggle APIのセットアップ
# kaggle CLIをインストール
uv tool install kaggle
KaggleのSettings画面でAPIトークンを発行し、以下の環境変数を設定する。新しいトークン形式（KGAT_で始まる）はkaggle.jsonではなく環境変数で管理する必要がある。
# ~/.zshrc に追記
export KAGGLE_API_TOKEN=KGAT_xxxxxxxxxxxxxxxxxx
2. カーネルのコピーとローカルへのpull
Kaggle上で参考にしたいカーネルを「Copy & Edit」で自分のカーネルとしてコピーする。その後、一度Kaggle UI上でSave Versionしておく（これをしないとAPI経由でpushできない）。
kaggle kernels pull kuriririn/your-kernel-name \
--path ./local/path \
--metadata
pullすると.ipynbとkernel-metadata.jsonがダウンロードされる。kernel-metadata.jsonにはInputのデータセット・モデル一覧が記録されており、Kaggle UI側で同じ環境を再現する際の参照情報になる。
3. Kaggle UI側でInputを設定する（手動）
kernel-metadata.jsonのdataset_sources・model_sources・competition_sourcesを確認し、Kaggle NotebookのInputタブから必要なデータセット・モデルを追加する。この作業だけはKaggle UIで行う必要がある（API経由での設定は現時点では非対応）。
4. VS CodeでKaggle Jupyter Serverに接続する
VS Codeで.ipynbファイルを開いた状態で、右上のカーネル選択メニューから Run → Kaggle Jupyter Server を選択する。すると画面右側にタブが開くので、Start Session を押してKaggleのセッションを起動する。セッションが立ち上がったら「VSCode Compatible URL」が表示されるのでコピーし、カーネル選択画面に貼り付けて接続する。
これで、ローカルのファイルをKaggle GPUで実行できる環境が整う。
5. 編集が終わったらKaggle側にpush
kaggle kernels push -p ./local/path
pushするとKaggle上のカーネルが更新される。デフォルトでは自動実行されてしまうため、kernel-metadata.jsonに以下を追記しておくことを推奨する。
"run_on_push": false
注意点
Notebookの自動同期はない
VS Codeで編集した内容はローカルにのみ保存される。Kaggle側に反映するには都度kaggle kernels pushが必要。逆にKaggle UI上で編集した場合も、ローカルには自動で反映されないためkaggle kernels pullで取得し直す必要がある。
Inputの設定はKaggle UIで行う
データセットやモデルの追加・変更はKaggle NotebookのInputタブからしか行えない。セッション開始前に必要なInputをすべて揃えておくこと。セッション中に追加したい場合はセッションを再起動することになる。
run_on_pushはデフォルトでtrue
run_on_pushを明示的にfalseにしないと、pushのたびにカーネルが自動実行される。enable_gpu: falseの場合はGPU枠は消費されないが、意図しない実行を避けるためにも最初からfalseにしておくのがベター。
初回pushの前にKaggle UIで一度保存が必要
Copy & Editで作ったカーネルは、Kaggle UI上で一度「Save Version」しないとAPIから存在を認識されずNotebook not foundエラーが出る。
Claude Code Skillsとの連携
今回のワークフローに合わせて、Claude Codeのカスタムスキルを3つ作成した。~/.claude/skills/<skill-name>/SKILL.mdに置くことでグローバルに呼び出せる。
/kaggle-kernel-pull
---
name: kaggle-kernel-pull
description: 他人のKaggleカーネル（notebook）のコードをローカルにダウンロードし、必要なInputの一覧を提示する。KaggleのURLまたは username/kernel-name 形式を受け取る。
---
# kaggle-kernel-pull
## Goal
指定されたKaggleカーネルのコードをローカルにダウンロードし、Kaggle UIで再現するために必要なInputの一覧を提示する。
## Steps
1. **引数を確認する**
- KaggleカーネルのURLまたは `username/kernel-name` 形式の文字列を受け取る。
- 指定がない場合はユーザーに入力を求める。
- URLの場合は `https://www.kaggle.com/code/username/kernel-name` 形式から `username/kernel-name` を抽出する。
2. **保存先を確認する**
- 保存先ディレクトリを確認する。指定がなければ現在の作業ディレクトリ配下に `username/kernel-name/` を作成して保存する。
- ディレクトリが既に存在する場合は上書きしてよいかユーザーに確認する。
3. **カーネルをpullする**
```bash
source ~/.zshrc && kaggle kernels pull <username>/<kernel-name> --path <保存先> --metadata
```
4. **ダウンロード結果を確認する**
保存先ディレクトリの内容を `ls` で確認し、取得できたファイル一覧をユーザーに報告する。
5. **kernel-metadata.json に `run_on_push: false` を追記する**
- `run_on_push` キーが存在しない場合は `"run_on_push": false` を追記して保存する。
- すでに存在する場合はそのままにする。
6. **kernel-metadata.json を解析してInputを提示する**
`dataset_sources`・`kernel_sources`・`competition_sources`・`model_sources` を読み取り整形して提示する。
7. **完了報告**
- ダウンロードしたファイルのパスを報告する。
- Kaggle UIでの追加手順を案内する。
KaggleカーネルのURLまたはusername/kernel-nameを受け取り、ローカルにpullする。kernel-metadata.jsonを解析してKaggle UIで追加すべきInputの一覧も提示してくれる。pullと同時にrun_on_push: falseを自動追記するので、うっかりpushで実行されるリスクを防げる。
/kaggle-kernel-push
---
name: kaggle-kernel-push
description: ローカルで編集したNotebookをKaggleにPushする。.ipynbファイルのパスまたはそのディレクトリを受け取り、kernel-metadata.json と合わせて kaggle kernels push を実行する。
---
# kaggle-kernel-push
## Goal
ローカルで編集・実行したKaggle NotebookをKaggleにPushして、Kaggle上のカーネルを更新する。
## Steps
1. **引数を確認する**
- `.ipynb` ファイルのパス、またはそのディレクトリパスを受け取る。
- 指定がない場合は、IDEで開いているファイルのディレクトリを使うか確認する。
2. **kernel-metadata.json の存在を確認する**
- 存在しない場合は中断し、`kaggle-kernel-pull` で取得するよう案内する。
3. **metadata の内容を確認する**
- `id`（Push先）と `code_file`（対象ファイル）をユーザーに提示して確認を求める。
4. **Pushする**
```bash
source ~/.zshrc && kaggle kernels push -p <対象ディレクトリ>
```
5. **完了報告**
- 成功時：カーネルIDとKaggle上のURLを報告する。
- エラー時：原因と対処法を案内する。
ローカルの.ipynbファイルをKaggleにpushする。push先のカーネルIDをユーザーに確認してから実行するため、誤送信を防げる。
/project-claude-init
---
name: project-claude-init
description: プロジェクトディレクトリにClaude関連の設定ファイル雛形を生成する。CLAUDE.md、.claude/settings.json、.claude/settings.local.json を空の状態で作成し、settings.local.json を .gitignore に追記する。
---
# project-claude-init
## Goal
指定されたプロジェクトディレクトリに、Claude Code 用の設定ファイル一式を空の雛形として作成する。
## Steps
1. **引数を確認する**
- ユーザーからプロジェクトのパスを受け取る。指定がなければ `pwd` を使うか確認する。
- パスが実在しない場合は中断する。
2. **ファイルを作成する**
- `<project>/CLAUDE.md`：`# Project Name` のみ
- `<project>/.claude/settings.json`：`{}`
- `<project>/.claude/settings.local.json`：`{}`
3. **`.gitignore` に追記する**
- 存在する場合：`.claude/settings.local.json` の行がなければ追記する。
- 存在しない場合：作成するかユーザーに確認する。
4. **完了報告**
作成したファイルの一覧をパス付きで報告する。
プロジェクトディレクトリにClaude Code用の設定ファイル（CLAUDE.md・.claude/settings.json・.claude/settings.local.json）の雛形を生成するスキル。Kaggleコンペの作業ディレクトリを作る際にも使っている。
まとめ
最終的なワークフローは以下のようになった。
| ステップ | 場所 |
|---|---|
| カーネルのCopy & Edit | Kaggle UI |
| Inputの設定 | Kaggle UI |
| ローカルにpull | ターミナル（/kaggle-kernel-pull） |
| コード編集・Claude Code連携 | ローカルVS Code |
| GPU実行・デバッグ | Kaggle Jupyter Server（VS Code経由） |
| Kaggleにpush | ターミナル（/kaggle-kernel-push） |
公式機能だけで実現できるのが思った以上に快適で、Notebookの手動同期さえ意識していれば大きなハマりどころもない。LLM系のコンペはモデルが大きく手元で動かせないケースが多いため、このワークフローが地味に効いてくると思っている。