kaggle-mcp
Runs local Python projects as background jobs on Kaggle, including submitting script kernels, uploading and managing datasets, monitoring job status and logs, downloading outputs, and cleaning up ephemeral jobs.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@kaggle-mcp run my train.py project on a GPU and download the outputs when it's done"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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-mcpRelated MCP server: AiAuN
How a job runs
submit_job(project_dir, entry, data_dir=None, datasets=[], gpu=False, internet=True, ephemeral=True)zips the project (without.git, virtualenvs, caches,kaggle_out/anddata_dir), embeds it in a generated script and pushes it as a private Kaggle script kernel.data_diris uploaded as a private dataset first. The call returns as soon as Kaggle accepts the job.On Kaggle the code is unpacked to
/tmp/kjob_code,requirements.txtis pip-installed if present, thenentryruns as__main__with cwd/kaggle/working.job_outputdownloads everything the job wrote to/kaggle/working(max ~20 GB) plus the log to<project_dir>/kaggle_out/<job_id>/. Forephemeraljobs it then deletes the kernel and the per-job dataset from Kaggle.
Environment variables available to the job:
Variable | Value |
| mount of |
| unpacked project code |
| epoch seconds when the run is stopped ( |
| output of the |
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 outputA 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 |
| start a job |
| status: |
| stdout/stderr tail (published after the run ends) |
| download outputs; cleans Kaggle for ephemeral jobs |
| delete a finished job's kernel and per-job 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 pyrightAvailable Tools
9 toolscleanup_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
Scored across 9 tools
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.
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.
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.
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
Related MCP Connectors
Remote shell and detached long-running jobs on your own machines — no SSH, open ports or VPN.
AI cloud for agents: launch GPUs, run jobs that stop their own billing, schedule runs.
Durable background job execution, async task scheduling, and state persistence for AI agents.
On-demand GPU nodes for agents: create nodes, run commands, and submit jobs, billed by the minute.
Related MCP Servers
- AlicenseNot gradedqualityFmaintenanceEnables AI agents and CLI users to drive Kaggle notebooks end-to-end—pull, edit, save new versions, run, monitor, and fetch logs—using a local stdio MCP server with a Kaggle API token.MIT
- FlicenseBqualityCmaintenanceEnables 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-
- AlicenseAqualityCmaintenanceEnables 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.81MIT
- AlicenseNot gradedqualityBmaintenanceEnables approved submission, monitoring, and retrieval of Kaggle CPU/GPU jobs, including two-stage preparation-to-training workflows, experiment comparison, artifact/log access, and SMTP completion notices.MIT