kaggle-free-gpu

MCP Server, CLI, and Agent Skill for Zero-Cost Tesla T4 x2 GPU Execution via the Kaggle REST API.

kaggle-free-gpu provides coding agents (Claude Code, Cursor, Antigravity) and ML engineers with programmatic access to Kaggle's dual NVIDIA Tesla T4 GPUs (2 x 15,360 MiB VRAM, Python 3.13, PyTorch 2.11+cu130) over direct REST and RPC calls to https://www.kaggle.com/api/v1.

Overview & Engineering Rationale

Coding agents can author PyTorch training loops, QLoRA fine-tuning pipelines, and CUDA/GGUF inference harnesses, but local agent execution environments rarely have dedicated GPU hardware. Kaggle provides up to 30 GPU-hours per rolling 7-day window on dual Tesla T4 accelerators at zero cost. However, automating Kaggle kernel execution from an autonomous agent fails with standard tooling due to undocumented API invariants:

1. Broken Official CLI Host: Kaggle CLI 1.8 routes requests to api.kaggle.com, which fails for kernel session operations. All requests must target https://www.kaggle.com/api/v1 directly.
2. Title-Derived Slug Resolution: Kaggle derives the canonical URL slug of a kernel from newTitle, ignoring the slug portion of id in kernel-metadata.json. Calling status or output endpoints with an id-based slug that diverges from the title-derived slug returns HTTP 403 Forbidden. Attempting to update an existing kernel when id does not match the title-derived slug is interpreted as a new kernel creation and fails with HTTP 409 Conflict.
3. Undocumented Service Endpoints: Standard REST paths such as /kernels/status/{owner}/{slug} and /kernels/output/{owner}/{slug} do not exist. Session status, output retrieval, and kernel deletion require JSON POST requests to kernels.KernelsApiService RPC endpoints.
4. Working Directory Output Saturation: ListKernelSessionOutput returns signed URLs for every file left in /kaggle/working. Leaving multi-gigabyte model checkpoints or GGUF weights in /kaggle/working causes output retrieval to fail with IncompleteRead.
5. Silent CPU Fallback in llama.cpp CUDA Releases: Prebuilt llama.cpp Ubuntu CUDA tarballs do not bundle libcudart.so.12, libcublas.so.12, or libcublasLt.so.12. Unless the companion cudart-llama-* archive from the same release is extracted into the same directory and added to LD_LIBRARY_PATH, the CUDA backend fails to register without emitting an error and executes on CPU (~2.7 tok/s vs ~37.7 tok/s on Tesla T4).

kaggle-free-gpu encodes these invariants into pre-push static validation, HEAD Content-Length output guards, a local rolling 7-day GPU quota ledger, a Model Context Protocol (MCP) server, and a terminal CLI (kfg).

Hardware & Runtime Specifications

Verified live on Kaggle GPU sessions (machineShape: NvidiaTeslaT4):

Installation

Using uv (Recommended)

# Install CLI (`kaggle-free-gpu` / `kfg`) and MCP server (`kaggle-free-gpu-mcp`) globally:
uv tool install git+https://github.com/ericmaddox/kaggle-free-gpu.git

# Or install in a local development checkout:
git clone https://github.com/ericmaddox/kaggle-free-gpu.git
cd kaggle-free-gpu
uv sync --extra dev

Using pip

pip install git+https://github.com/ericmaddox/kaggle-free-gpu.git

Authentication

Generate a Kaggle API token at https://www.kaggle.com/settings. Credentials are resolved in the following order and are never logged or written to repository files:

1. KAGGLE_API_TOKEN environment variable (Bearer KGAT_...)
2. ~/.kaggle/access_token file (Bearer KGAT_...)
3. KAGGLE_USERNAME and KAGGLE_KEY environment variables (Basic auth)
4. ~/.kaggle/kaggle.json file (Basic auth)

mkdir -p ~/.kaggle
echo "KGAT_your_token_here" > ~/.kaggle/access_token
chmod 600 ~/.kaggle/access_token

MCP Server Configuration

Register kaggle-free-gpu-mcp in your agent's MCP configuration (mcp_config.json, .mcp.json, or claude_desktop_config.json):

{
  "mcpServers": {
    "kaggle-free-gpu": {
      "command": "kaggle-free-gpu-mcp",
      "env": {
        "KAGGLE_API_TOKEN": "KGAT_your_token_here"
      }
    }
  }
}

MCP Tools Reference

CLI Usage (kfg / kaggle-free-gpu)

# 1. Estimate remaining rolling 7-day GPU quota
uv run kfg quota

# 2. Validate and push a kernel directory, poll until COMPLETE, and download outputs
uv run kfg push examples/01_gpu_smoke_test --wait --out-dir outputs/smoke

# 3. Check execution status of a kernel
uv run kfg status <owner>/kfg-gpu-smoke-test

# 4. Pull output files and execution logs with a 500 MB per-file safety guard
uv run kfg output <owner>/kfg-gpu-smoke-test --out-dir outputs/smoke --max-size-mb 500

# 5. List your own kernels
uv run kfg list --mine

# 6. Permanently delete a kernel (interactive confirmation or --yes)
uv run kfg delete <owner>/kfg-gpu-smoke-test

Note on <owner> placeholder resolution: All kernel-metadata.json files in examples/ use "id": "<owner>/<slug>". kaggle-free-gpu automatically resolves <owner> from your authenticated Kaggle account at push time.

Benchmarks: CPU vs. Kaggle Tesla T4 x2

Measured live on Kaggle (2 x Tesla T4, Python 3.13.16, torch 2.11.0+cu130) across the repository's reference workflows:

CLI Execution Transcript

$ uv run kfg push examples/02_qlora_finetune --wait --out-dir outputs/qlora
+--------------------------- Kaggle Free-GPU Push ----------------------------+
| Pushed successfully!                                                        |
| Ref: <owner>/kfg-qlora-finetune-demo                                        |
| Title: KFG QLoRA Finetune Demo                                              |
| Version: 3                                                                  |
| GPU Enabled: True | Private: True                                           |
| URL: https://www.kaggle.com/code/<owner>/kfg-qlora-finetune-demo            |
+-----------------------------------------------------------------------------+
[0s]  <owner>/kfg-qlora-finetune-demo -> QUEUED
[10s] <owner>/kfg-qlora-finetune-demo -> RUNNING
[50s] <owner>/kfg-qlora-finetune-demo -> COMPLETE
Output downloaded to: outputs/qlora (runtime: 32.99s)
+---------------------------------- Stdout -----------------------------------+
| {                                                                           |
|   "workflow": "qlora_finetune",                                             |
|   "gpu_name": "Tesla T4",                                                   |
|   "gpu_count": 2,                                                           |
|   "trainable_lora_params": 1878016,                                         |
|   "frozen_4bit_packed_mb": 38.0,                                            |
|   "steps": 60,                                                              |
|   "initial_loss": 8.9066,                                                   |
|   "final_loss": 0.0005,                                                     |
|   "gpu_train_seconds": 6.436,                                               |
|   "tokens_per_second": 19092.1,                                             |
|   "saved_adapter_file": "lora_adapter.pt"                                   |
| }                                                                           |
| CLEANUP DONE                                                                |
+-----------------------------------------------------------------------------+

Reference Workflows (examples/)

• examples/01_gpu_smoke_test: Queries torch.cuda device properties and nvidia-smi, executes an FP16 4096 x 4096 GEMM across all attached GPUs, and writes gpu_smoke_report.json.
• examples/02_qlora_finetune: Quantizes base transformer linear layers into packed 4-bit uint8 buffers with per-block FP16 scales, attaches trainable FP32/FP16 LoRA adapters (lora_A, lora_B), runs 60 optimization steps with gradient clipping, exports only the compact adapter (lora_adapter.pt) and qlora_metrics.json, and cleans up /tmp.
• examples/03_inference_bench: Benchmarks autoregressive transformer token generation across Tesla T4 (float16) and CPU (float32), and provides setup_llamacpp_cuda() for downloading and configuring both the llama.cpp CUDA binary tarball and its required cudart- companion runtime archive.
• examples/04_data_processing: Executes L2 normalization, 256M-pair exact cosine similarity top-k retrieval, and 32-component low-rank SVD (torch.pca_lowrank) over 32,000 x 768 document embeddings on Tesla T4 vs CPU.

Repository Structure

kaggle-free-gpu/
├── SKILL.md                        # Agent skill specification, workflow, and operational rules
├── pyproject.toml                  # Hatchling build config, dependencies, and entrypoints
├── src/
│   └── kaggle_free_gpu/
│       ├── __init__.py
│       ├── client.py               # Direct REST & KernelsApiService RPC client
│       ├── models.py               # Pydantic schemas and pre-push metadata validator
│       ├── quota.py                # Local rolling 7-day GPU quota ledger
│       ├── server.py               # FastMCP server exposing the 6 Kaggle GPU tools
│       └── cli.py                  # Terminal CLI (`kaggle-free-gpu` / `kfg`)
├── examples/
│   ├── 01_gpu_smoke_test/
│   ├── 02_qlora_finetune/
│   ├── 03_inference_bench/
│   └── 04_data_processing/
├── scripts/
│   └── validate_live.py            # End-to-end live validation suite against Kaggle REST API
└── tests/
    └── test_client_and_rules.py    # Unit tests for slug rules, quota math, and safety guards

Development & Verification

# Run unit tests
uv run pytest -v

# Run linter
uv run ruff check src tests scripts examples

# Run live end-to-end GPU validation against Kaggle REST API (requires KAGGLE_API_TOKEN)
uv run python scripts/validate_live.py

License

MIT License. See LICENSE.