Skip to main content
Glama

kaggle-mcp

MCP server that runs local Python projects as background jobs on Kaggle's free machines (12 h per run, CPU or GPU).

Setup

# credentials: token from kaggle.com/settings/api → "Generate New Token"
mkdir -p ~/.kaggle && chmod 700 ~/.kaggle   # save token to ~/.kaggle/access_token, chmod 600

uv tool install --editable .                # installs `kaggle-mcp` and `kjob` to ~/.local/bin
claude mcp add --scope user kaggle-jobs -- ~/.local/bin/kaggle-mcp

Related MCP server: AiAuN

How a job runs

  1. submit_job(project_dir, entry, data_dir=None, datasets=[], gpu=False, internet=True, ephemeral=True) zips the project (without .git, virtualenvs, caches, kaggle_out/ and data_dir), embeds it in a generated script and pushes it as a private Kaggle script kernel. data_dir is uploaded as a private dataset first. The call returns as soon as Kaggle accepts the job.

  2. On Kaggle the code is unpacked to /tmp/kjob_code, requirements.txt is pip-installed if present, then entry runs as __main__ with cwd /kaggle/working.

  3. job_output downloads everything the job wrote to /kaggle/working (max ~20 GB) plus the log to <project_dir>/kaggle_out/<job_id>/. For ephemeral jobs it then deletes the kernel and the per-job dataset from Kaggle.

Environment variables available to the job:

Variable

Value

KJOB_DATA_DIR

mount of data_dir (read-only); subdirectories keep their structure

KJOB_CODE_DIR

unpacked project code

KJOB_DEADLINE

epoch seconds when the run is stopped (time_limit_h, default 11.5 h)

KJOB_RESUME_DIR

output of the resume_from job (read-only), if given

Runs longer than 12 hours

Kaggle stops every run after 12 hours. A job is stopped at KJOB_DEADLINE instead, before that cutoff, so everything it wrote to the working directory is saved; job_output then reports incomplete: true and keeps the kernel on Kaggle. Submit the same job again with resume_from=<job_id> to continue: the previous output is mounted at KJOB_RESUME_DIR, without a round trip through the local machine. Once a resumed part is downloaded, the part it continued from is deleted from Kaggle.

import json, os
from pathlib import Path

resume = os.environ.get("KJOB_RESUME_DIR")
state = json.loads((Path(resume) / "ckpt.json").read_text()) if resume else {"step": 0}
while state["step"] < TOTAL_STEPS:
    train_one_step(state)
    state["step"] += 1
    Path("ckpt.json").write_text(json.dumps(state))  # cwd is the job's output

A script that stops early on its own (for example by checking KJOB_DEADLINE) should create the file kjob_incomplete in its cwd so job_output reports it as incomplete. For a chain of parts, upload the input data once with upload_dataset and pass datasets=[...] rather than data_dir.

Tools

Tool

Purpose

submit_job

start a job

job_status, list_jobs

status: queued, running, complete, error, cancel_*

job_logs

stdout/stderr tail (published after the run ends)

job_output

download outputs; cleans Kaggle for ephemeral jobs

cleanup_job

delete a finished job's kernel and per-job dataset

upload_dataset, list_datasets, delete_dataset

data shared across jobs; delete refuses while an unfinished job uses it

Waiting for a job

kjob wait <job_id>   # polls every 60 s, prints status changes, exit 0 = complete, 1 = failed
kjob list
kjob pending         # jobs not downloaded yet or stopped and not resumed; local store only (SessionStart hook)

Job records live in ~/.local/share/kaggle-mcp/jobs.json, so jobs remain visible after a restart.

Development

uv run pytest && uv run ruff check . && uv run pyright

Available Tools

9 tools
cleanup_jobA

Delete a finished job's kernel (with its outputs) and per-job dataset from Kaggle.

Inputs: job_id (required). Returns: object

delete_datasetA

Delete a dataset created by upload_dataset. Refuses if an unfinished job uses it.

Inputs: ref (required). Returns: result

job_logsB

stdout/stderr of a job's latest run (last tail_chars characters; 0 = all).

Kaggle usually publishes the log only after the run finishes.

Inputs: job_id (required), tail_chars. Returns: result

job_outputA

Download a finished job's output files (default: <project_dir>/kaggle_out/<job_id>/).

For ephemeral jobs the kernel and its per-job dataset are then deleted from Kaggle, unless
the run stopped at its time limit (incomplete): then it is kept so a new job can resume it.

Inputs: job_id (required), dest_dir. Returns: object

job_statusB

Current status of a job: queued, running, complete, error or cancel_*.

Inputs: job_id (required). Returns: object

list_datasetsB

Datasets uploaded with upload_dataset that still exist.

Inputs: no named parameters. Returns: result

list_jobsA

All jobs submitted from this machine, newest first. refresh=True asks Kaggle for status.

Inputs: refresh. Returns: result

submit_jobA

Run a Python project on Kaggle as a private background job; returns immediately.

The project's code (excluding .git, virtualenvs, caches and data_dir) is bundled; on Kaggle
`entry` runs as `__main__` with cwd=/kaggle/working. Files written there become the job's
output (limit ~20 GB). If the project has requirements.txt it is pip-installed first
(needs internet=True). Each run is limited to 12 hours.

Args:
    project_dir: Local project directory.
    entry: Script to run, relative to project_dir (e.g. "train.py").
    data_dir: Optional local directory uploaded as a private dataset for this job only.
        On Kaggle its path is in env var KJOB_DATA_DIR. Subdirectories are uploaded zipped.
    datasets: Existing Kaggle dataset refs ("owner/slug") to attach, mounted under
        /kaggle/input. Use upload_dataset for data shared by many jobs.
    gpu: Request a GPU (counts against the weekly GPU quota).
    internet: Allow network access (pip installs, downloads).
    ephemeral: Delete the job's kernel, outputs and per-job dataset from Kaggle after
        job_output downloads them, so Kaggle storage does not fill up.
    resume_from: job_id of a finished job whose output (e.g. checkpoints) this job continues
        from; on Kaggle its path is in env var KJOB_RESUME_DIR (read-only).
    time_limit_h: Stop the run after this many hours (max 12, Kaggle's cutoff) so its
        output is saved. Env var KJOB_DEADLINE holds the deadline as epoch seconds; the run
        is stopped there if the script has not exited, and job_output reports incomplete.

Inputs: entry (required), project_dir (required), gpu, data_dir, +5 more. Returns: object

upload_datasetA

Upload a local directory as a private Kaggle dataset to reuse across jobs.

Pass the returned ref in submit_job(datasets=[...]). Not deleted automatically;
use delete_dataset when done.

Inputs: name (required), data_dir (required). Returns: object

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.7/5.0

    Scored across 9 tools

    Disambiguation4/5

    Each tool maps to a distinct action in the job or dataset lifecycle, and descriptions clarify the boundaries between look-alike pairs (job_status vs list_jobs, job_logs vs job_output). The only mild overlap is cleanup_job, which deletes a kernel plus its per-job dataset, versus delete_dataset for uploaded datasets — but the descriptions make that distinction explicit.

    Naming Consistency4/5

    Eight of nine names follow a predictable snake_case verb_noun pattern (submit_job, list_jobs, upload_dataset, delete_dataset). The read-side tools (job_status, job_logs, job_output) drop the verb and lead with the noun, a minor but noticeable inconsistency in an otherwise clean scheme.

    Tool Count5/5

    Nine tools is well scoped: six cover the remote job lifecycle and three cover reusable datasets, with no filler. Nothing looks redundant or missing from a count perspective.

    Completeness4/5

    The job lifecycle (submit, status, list, logs, output, cleanup) and dataset lifecycle (upload, list, delete) are both well covered. The notable gap is cancellation — job_status reports cancel_* states, yet there is no tool to cancel a running job, forcing reliance on time_limit_h.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      B
      quality
      C
      maintenance
      Enables running ML experiments from a local laptop by coordinating GitHub for code, Kaggle for data and GPU training, Weights & Biases for tracking runs, and Google Drive for small artifacts.
      14
      -
    • A
      license
      A
      quality
      C
      maintenance
      Enables AI agents and their users to submit, route, and monitor training jobs across free-tier GPU clouds (Kaggle, Colab, Lightning, local MPS) through a local daemon that tracks quota, explains routing decisions, and gates long or secret-reading agent jobs behind human approval.
      8
      1
      MIT