kagglerun

---

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

---

Why KaggleRun?

Feature	KaggleRun	Kaggle Web	Colab	Cloud GPU
No browser needed	Yes	No	No	No
CLI-native	Yes	No	No	Partial
AI agent ready (MCP)	Yes	No	No	No
Free GPU access	Yes	Yes	Limited	No
Real-time output	Yes	Yes	Yes	Yes
Cost	$0	$0	$0-10/mo	$$$$

---

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..."

Note: For set, do NOT use quotes around the URL. For setx, quotes are required.

# 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%

Note: After setx, close and reopen your terminal (or restart your IDE/Claude) for changes to take effect.

# 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

Config file: C:\Users\{username}\AppData\Roaming\Claude\claude_desktop_config.json

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

Config file: ~/Library/Application Support/Claude/claude_desktop_config.json

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

Config file: ~/.config/Claude/claude_desktop_config.json

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

Claude Code (CLI)

Config file: ~/.claude/mcp_settings.json

OS	Full Path
Windows	C:\Users\{username}\.claude\mcp_settings.json
macOS	/Users/{username}/.claude/mcp_settings.json
Linux	/home/{username}/.claude/mcp_settings.json

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

Other MCP-Compatible Tools

Tool	Config Location
Cursor	Settings → MCP → Add Server
Cline	.cline/mcp_settings.json
Continue	~/.continue/config.json

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

Tool	Description
execute_python	Run Python code on GPU
get_gpu_info	Get GPU model, memory, driver
get_system_info	Python version, PyTorch, CUDA
list_files	Browse /kaggle/working/
read_file	Read remote text files
save_file	Save content to files
download_file	Download files (base64)
test_connection	Verify kernel connectivity

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
)

Method	Description
execute(code, timeout)	Execute Python code
run_file(path, timeout)	Run local .py file
upload_file(local, remote)	Upload to /kaggle/working/
download_file(path)	Download as bytes
save_text(name, content)	Save text file
read_file(path)	Read text file
list_files(path)	List directory
get_gpu_info()	GPU information
get_system_info()	System information
test_connection()	Test connectivity
interrupt_kernel()	Stop execution

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

Limitation	Details
Session timeout	~12 hours of inactivity
Token expiration	Get fresh URL when disconnected
GPU quota	~30 hours/week (free accounts)
File persistence	Only during active session

---

Troubleshooting

• Ensure notebook shows "Running" status in Kaggle
• Get a fresh URL (tokens expire)
• Check GPU is enabled in notebook settings

• KaggleRun auto-interrupts busy kernels
• Use --timeout for long operations
• Check if notebook is running other code

• Enable GPU: Settings > Accelerator > GPU
• Check quota at kaggle.com/me/quota

---

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

---