mcp-server-kaggle-exec

<!-- mcp-name: io.github.pdwi2020/mcp-server-kaggle-exec -->

MCP server that executes Python code on Kaggle GPU runtimes (T4 x2, P100, TPU) from any MCP-compatible AI assistant — Claude Code, Claude Desktop, Gemini CLI, Cline, and others. Run GPU-accelerated code (CUDA, PyTorch, TensorFlow) without local GPU hardware using Kaggle's free 30hr/week GPU quota.

Prerequisites

• Python 3.10+
• A Kaggle account
• Kaggle API credentials: either KAGGLE_API_TOKEN env var (KGAT_* token) or ~/.kaggle/kaggle.json (see Authentication)

Installation

pip install mcp-server-kaggle-exec

Or run directly with uvx:

uvx mcp-server-kaggle-exec

Configuration

Claude Code

Add to your project's .mcp.json or ~/.claude/.mcp.json:

{
  "mcpServers": {
    "kaggle-exec": {
      "command": "mcp-server-kaggle-exec"
    }
  }
}

Or via the CLI:

claude mcp add kaggle-exec mcp-server-kaggle-exec

Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "kaggle-exec": {
      "command": "mcp-server-kaggle-exec"
    }
  }
}

Gemini CLI

gemini mcp add kaggle-exec -- mcp-server-kaggle-exec

Tools

kaggle_execute

Execute inline Python code on a Kaggle GPU kernel.

Parameter	Type	Default	Description
code	string	—	Python code to execute (required)
enable_gpu	bool	true	Whether to request GPU acceleration
timeout	int	600	Max wait time in seconds

Returns JSON with stdout, stderr, status, output_files, and execution_time.

kaggle_execute_file

Execute a local .py file on a Kaggle GPU kernel.

Parameter	Type	Default	Description
file_path	string	—	Path to a local .py file (required)
enable_gpu	bool	true	Whether to request GPU acceleration
timeout	int	600	Max wait time in seconds

kaggle_execute_notebook

Execute code and download all generated output files (images, models, CSVs, etc.).

Parameter	Type	Default	Description
code	string	—	Python code to execute (required)
output_dir	string	—	Local directory for downloaded artifacts (required)
enable_gpu	bool	true	Whether to request GPU acceleration
timeout	int	600	Max wait time in seconds

Output files are downloaded to output_dir. To save files for download, write them to the current directory in your Kaggle code.

Examples

Check GPU availability:

kaggle_execute(code="import torch; print(torch.cuda.is_available()); print(torch.cuda.get_device_name(0))")

Run nvidia-smi:

kaggle_execute(code="import subprocess; print(subprocess.run(['nvidia-smi'], capture_output=True, text=True).stdout)")

Train a model and download weights:

kaggle_execute_notebook(
    code="import torch; model = torch.nn.Linear(10, 1); torch.save(model.state_dict(), 'model.pt')",
    output_dir="./outputs"
)

CPU-only execution (faster startup):

kaggle_execute(code="print('Hello from Kaggle!')", enable_gpu=False)

How It Works

Unlike Google Colab (which uses real-time WebSocket execution), Kaggle uses batch execution:

1. Your code is pushed as a private Kaggle kernel
2. Kaggle queues and runs the kernel (30-120s startup + execution time)
3. Once complete, the output log and files are downloaded
4. The kernel is cleaned up (left as private)

This means there's no streaming output — you get results only after execution completes.

Authentication

Two authentication methods are supported:

Option 1: KGAT_* Access Token (recommended)

Kaggle API v2 access tokens (KGAT_* format) work via environment variable:

export KAGGLE_API_TOKEN=KGAT_your_token_here

To get a token: go to kaggle.com/settings → API → Create New Access Token.

When using with MCP, pass the env var in your server config:

{
  "mcpServers": {
    "kaggle-exec": {
      "command": "mcp-server-kaggle-exec",
      "env": {
        "KAGGLE_API_TOKEN": "KGAT_your_token_here"
      }
    }
  }
}

Option 2: Legacy kaggle.json

Place your Kaggle API key at ~/.kaggle/kaggle.json:

1. Go to kaggle.com/settings
2. Scroll to API section
3. Click Create New Token
4. Move the downloaded kaggle.json to ~/.kaggle/kaggle.json
5. Set permissions: chmod 600 ~/.kaggle/kaggle.json

GPU Quota

Kaggle provides ~30 hours of free GPU per week. The API supports enable_gpu: true/false but does not allow selecting specific GPU types (T4 vs P100) — Kaggle assigns the GPU automatically.

For CPU-only tasks, set enable_gpu=False to avoid consuming GPU quota.

Troubleshooting

"Kaggle authentication failed" — Ensure either KAGGLE_API_TOKEN env var is set (KGAT_* token) or ~/.kaggle/kaggle.json exists. See Authentication above.

"Kernel timed out" — Increase the timeout parameter. Kaggle kernel startup can take 30-120 seconds, plus execution time.

"GPU quota exceeded" — You've used your ~30hr weekly GPU quota. Wait for the weekly reset or use enable_gpu=False for CPU-only execution.

"Kernel status: error" — Check the stderr in the response for Python errors in your code.

Comparison with mcp-server-colab-exec

Aspect	colab-exec	kaggle-exec
Execution model	Real-time (WebSocket)	Batch (push + poll)
Startup time	~10-30s	~30-120s
Auth	Google OAuth2 (browser)	API token file
GPU types	T4, L4	T4 x2, P100, TPU
GPU selection	Can pick T4/L4	API only supports on/off
Free quota	Usage-based	~30 hr/week
Output	Streaming	After completion

License

MIT