KaggleRun

Execute Python on Kaggle's FREE GPUs from your terminal. No browser needed.

Quick Start • Features • MCP Server • API • Contributing

What is KaggleRun?

KaggleRun bridges your local terminal to Kaggle's free GPU infrastructure. Perfect for:

• AI Coding Agents - Claude Code, Cursor, Cline can execute GPU code natively
• ML Engineers - Train models without leaving your terminal
• Data Scientists - Run experiments on free T4/P100/H100 GPUs

pip install kagglerun
kagglerun --url "$KAGGLE_URL" "import torch; print(torch.cuda.get_device_name(0))"
# Output: Tesla T4

Tesla T4 - Quick Commands

H100 80GB - Competition Workflow

Why KaggleRun?

Quick Start

Step 1: Get Your Kaggle URL

1. Open kaggle.com/code and create/open a notebook
2. Enable GPU: Settings > Accelerator > GPU T4 x2 (or P100)
3. Click Run menu (top left) > Kaggle Jupyter Server
4. Copy the VSCode Compatible URL from the right panel

Step 2: Install

pip install kagglerun

Step 3: Set Environment Variable

:: Temporary (current session only)
set KAGGLE_JUPYTER_URL=https://kkb-production.jupyter-proxy.kaggle.net?token=eyJ...

:: Permanent (persists after restart)
setx KAGGLE_JUPYTER_URL "https://kkb-production.jupyter-proxy.kaggle.net?token=eyJ..."

# Temporary (current session only)
$env:KAGGLE_JUPYTER_URL = "https://kkb-production.jupyter-proxy.kaggle.net?token=eyJ..."

# Permanent (user level)
[Environment]::SetEnvironmentVariable("KAGGLE_JUPYTER_URL", "https://kkb-production.jupyter-proxy.kaggle.net?token=eyJ...", "User")

# Temporary (current session only)
export KAGGLE_JUPYTER_URL="https://kkb-production.jupyter-proxy.kaggle.net?token=eyJ..."

# Permanent - add to ~/.bashrc or ~/.zshrc
echo 'export KAGGLE_JUPYTER_URL="https://kkb-production.jupyter-proxy.kaggle.net?token=eyJ..."' >> ~/.bashrc
source ~/.bashrc

# Skip environment variable entirely
kagglerun --url "https://kkb-production.jupyter-proxy.kaggle.net?token=eyJ..." "print('Hello GPU!')"

Step 4: Run!

# Test connection
kagglerun --test

# Check GPU
kagglerun --gpu-info

# Execute code
kagglerun "import torch; print(f'CUDA: {torch.cuda.is_available()}')"

# Run a Python file
kagglerun train.py

Features

CLI Commands

# Execute inline Python code
kagglerun "print('Hello from Kaggle GPU!')"

# Execute a local Python file
kagglerun my_script.py

# GPU and system information
kagglerun --gpu-info
kagglerun --system-info

# File operations
kagglerun --list-files                    # List /kaggle/working/
kagglerun --upload data.csv               # Upload file
kagglerun --download model.pkl -o ./      # Download file
kagglerun --read output.txt               # Read remote file

# Connection
kagglerun --test                          # Test connection
kagglerun --timeout 300 long_script.py    # Custom timeout

Python API

from kagglerun import KaggleExecutor

# Connect to Kaggle
executor = KaggleExecutor("https://your-kaggle-url?token=...")

# Execute code
result = executor.execute("""
import torch
print(f"GPU: {torch.cuda.get_device_name(0)}")
print(f"Memory: {torch.cuda.get_device_properties(0).total_memory / 1e9:.1f} GB")
""")

# File operations
executor.save_text("config.json", '{"epochs": 10}')
executor.upload_file("local_data.csv", "data.csv")
data = executor.download_file("results.csv")

# Get info
executor.get_gpu_info()
executor.get_system_info()
executor.list_files()

MCP Server

KaggleRun includes a Model Context Protocol (MCP) server, enabling AI assistants like Claude to execute code on Kaggle GPUs as a native tool.

Step 1: Install

pip install kagglerun[mcp]

Step 2: Set Environment Variable (Recommended)

Set KAGGLE_JUPYTER_URL as a permanent system variable so all AI tools can use it automatically.

:: Set permanently (requires terminal restart)
setx KAGGLE_JUPYTER_URL "https://kkb-production.jupyter-proxy.kaggle.net?token=eyJ..."

:: Also set for current session
set KAGGLE_JUPYTER_URL=https://kkb-production.jupyter-proxy.kaggle.net?token=eyJ...

:: Verify (in NEW terminal)
echo %KAGGLE_JUPYTER_URL%

# Set permanently (Machine level - all users)
[Environment]::SetEnvironmentVariable("KAGGLE_JUPYTER_URL", "https://kkb-production.jupyter-proxy.kaggle.net?token=eyJ...", "Machine")

# Or User level only
[Environment]::SetEnvironmentVariable("KAGGLE_JUPYTER_URL", "https://kkb-production.jupyter-proxy.kaggle.net?token=eyJ...", "User")

# Also set for current session
$env:KAGGLE_JUPYTER_URL = "https://kkb-production.jupyter-proxy.kaggle.net?token=eyJ..."

# Verify
echo $env:KAGGLE_JUPYTER_URL

# Add to ~/.bashrc (Linux) or ~/.zshrc (macOS)
echo 'export KAGGLE_JUPYTER_URL="https://kkb-production.jupyter-proxy.kaggle.net?token=eyJ..."' >> ~/.bashrc

# Reload
source ~/.bashrc

# Verify
echo $KAGGLE_JUPYTER_URL

Step 3: Configure MCP Client

Add KaggleRun to your AI assistant's MCP configuration.

Claude Desktop

{
  "mcpServers": {
    "kagglerun": {
      "command": "python",
      "args": ["-m", "kagglerun.mcp_server"]
    }
  }
}

{
  "mcpServers": {
    "kagglerun": {
      "command": "python3",
      "args": ["-m", "kagglerun.mcp_server"]
    }
  }
}

{
  "mcpServers": {
    "kagglerun": {
      "command": "python3",
      "args": ["-m", "kagglerun.mcp_server"]
    }
  }
}

Claude Code (CLI)

{
  "mcpServers": {
    "kagglerun": {
      "command": "python",
      "args": ["-m", "kagglerun.mcp_server"]
    }
  }
}

Other MCP-Compatible Tools

Alternative: Pass URL in Config

If you prefer not to set a system environment variable, include the URL directly in the MCP config:

{
  "mcpServers": {
    "kagglerun": {
      "command": "python",
      "args": ["-m", "kagglerun.mcp_server"],
      "env": {
        "KAGGLE_JUPYTER_URL": "https://kkb-production.jupyter-proxy.kaggle.net?token=eyJ..."
      }
    }
  }
}

Verify MCP Server

Test the server is working:

# Should start without errors (Ctrl+C to exit)
python -m kagglerun.mcp_server

Available Tools

Example Conversation

You: Train a simple neural network on the Kaggle GPU

Claude: Uses execute_python to run PyTorch training on Kaggle's free GPU

Use Cases

ML Model Training

result = executor.execute("""
import torch
import torch.nn as nn
from torchvision import models

# Load pretrained ResNet50
model = models.resnet50(weights='DEFAULT').cuda()

# Inference test
x = torch.randn(16, 3, 224, 224).cuda()
with torch.amp.autocast('cuda'):
    out = model(x)

print(f"Output: {out.shape}")
print(f"GPU Memory: {torch.cuda.memory_allocated()/1e9:.2f} GB")
""")

LLM Inference

result = executor.execute("""
from transformers import pipeline

generator = pipeline('text-generation', model='gpt2', device=0)
output = generator("The future of AI is", max_length=50)
print(output[0]['generated_text'])
""", timeout=300)

Data Processing

result = executor.execute("""
import pandas as pd
import numpy as np

# Generate large dataset
df = pd.DataFrame(np.random.randn(1_000_000, 50))
print(f"Shape: {df.shape}")
print(f"Memory: {df.memory_usage(deep=True).sum() / 1e6:.1f} MB")

# Save for download
df.to_parquet('/kaggle/working/data.parquet')
""")

# Download result
data = executor.download_file("data.parquet")

API Reference

KaggleExecutor

KaggleExecutor(
    base_url: str,              # Kaggle Jupyter URL
    verbose: bool = True,       # Print status messages
    timeout: int = 120,         # Default timeout (seconds)
    on_output: Callable = None  # Streaming output callback
)

Convenience Function

from kagglerun import connect

executor = connect("https://your-url")  # Raises ConnectionError if fails

How It Works

┌─────────────────────┐          ┌─────────────────────┐
│   Your Terminal     │          │   Kaggle Jupyter    │
│   ─────────────     │  REST    │   ──────────────    │
│                     │◄────────►│   Kernel Manager    │
│   kagglerun CLI     │          │                     │
│   Python API        │  WS      │   Python Kernel     │
│   MCP Server        │◄════════►│   GPU: T4/P100/H100 │
│                     │          │                     │
└─────────────────────┘          └─────────────────────┘
      Local Machine                   Kaggle Cloud

• REST API - Kernel lifecycle management
• WebSocket - Real-time code execution & streaming output
• Base64 - Binary file transfers

Limitations

Troubleshooting

Contributing

Contributions welcome! See CONTRIBUTING.md.

git clone https://github.com/Letemoin/kagglerun
cd kagglerun
pip install -e ".[dev]"
pytest tests/ -v

License

MIT License - see LICENSE

Acknowledgments

• Kaggle - Free GPU infrastructure
• Jupyter - Notebook protocol
• Anthropic - MCP specification

If KaggleRun helps your workflow, give it a star!