Skip to main content
Glama

Link2Kaggle-Colab

Local MCP server and CLI to submit jobs to Kaggle and Google Colab from your machine.

CI Python License Release

English | 简体中文

Status

v1.0.0 — initial public release on main (changelog).

  • Default mode is mock: no real account, network, GPU, or Colab compute units (CCU).

  • Real GPU/CCU submit needs both mode: real and allow_real_jobs: true.

  • Mock quota / balance / membership text is a TEST FIXTURE, not a live account.

Related MCP server: mcp-server-colab-exec

Features

  • Providers: Kaggle, Google Colab, and offline fake runner

  • Surfaces: SDK (link2kaggle_colab.Client), CLI (l2kc), stdio MCP server

  • Scheduler: recommend / auto placement with quota-aware guards

  • Jobs: SQLite job manager, list / reconcile, idempotency keys

  • Multi-account: credential references in config (paths / env / keyring), no secrets in YAML

Piece

Name

Distribution

link2kaggle-colab

Import package

link2kaggle_colab

SDK

link2kaggle_colab.Client

CLI

l2kc

MCP (stdio)

link2kaggle-colab-mcp or python -m link2kaggle_colab.mcp

Skill

skills/link2kaggle-colab/SKILL.md

Quick start

python3 -m venv .venv
.venv/bin/pip install -e '.[dev]'
.venv/bin/l2kc doctor
.venv/bin/l2kc quota
.venv/bin/l2kc submit examples/train_example.py --provider fake

Local CI gate:

make ci
# or: ./scripts/ci.sh

l2kc doctor prints a MOCK MODE line on stderr (not part of --json stdout). Linux/WSL notes: docs/linux-wsl-setup.md.

Safety

Connect only trusted MCP clients. Downloads are confined to artifact_root (default ./l2kc-artifacts); paths outside that root raise PathSecurityError. In the MCP process, local fake exec is off unless L2KC_ALLOW_FAKE_EXEC=1. Real billed work is double-gated (mode: real + allow_real_jobs: true).

See SECURITY.md and docs/known-limitations.md.

MCP setup (Cursor / stdio)

{
  "mcpServers": {
    "link2kaggle-colab": {
      "command": "link2kaggle-colab-mcp"
    }
  }
}

From a virtualenv:

{
  "mcpServers": {
    "link2kaggle-colab": {
      "command": ".venv/bin/python",
      "args": ["-m", "link2kaggle_colab.mcp"]
    }
  }
}

Canonical tools use the gpu_* prefix (also registered as l2kc_*). Agent guidance: skills/link2kaggle-colab/SKILL.md.

Real mode (spend warning)

Real Kaggle/Colab auth and GPU/CCU jobs can cost money or quota. Read docs/real-auth-setup.md before enabling:

  1. mode: real in config

  2. allow_real_jobs: true for any GPU/CCU submit

Either flag alone does not submit billed work. Default CI never burns GPU or Colab CCU.

Docs index

Doc

Topic

SECURITY.md

Trust boundary, reporting

CONTRIBUTING.md

Dev setup, make ci, mock-first

docs/known-limitations.md

Limitations and Won't-Fix

docs/mock-mode.md

Mock defaults

docs/real-auth-setup.md

Real credentials

docs/accounts.md

Multi-account

docs/architecture.md

Design overview

docs/linux-wsl-setup.md

Linux/WSL

CHANGELOG.md

Version history

config.example.yaml

Config template

CLI (cheat sheet)

Global options go before the subcommand: l2kc --config ./l2kc.yaml doctor.

Command

Purpose

l2kc doctor

Mode, state dir, CLI presence, auth (does not run kaggle/colab)

l2kc providers / quota / resources

Providers and fixtures (mock) or live reads (real)

l2kc recommend …

Pick a backend; does not submit

l2kc submit FILE [--provider auto|kaggle|colab|fake] …

Submit .py / .ipynb

l2kc status / logs / download / cancel

Job lifecycle

l2kc accounts … / l2kc jobs …

Accounts and local job store

Known errors print error[<code>]: <message> on stderr and exit 2. Full flag lists: run l2kc --help / l2kc submit --help.

Limitations (short)

  • Mock quotas are fixtures; default Colab CCU rates are unverified.

  • Kaggle cancel is not_supported (official CLI has no cancel).

  • Remote MCP transports are refused; stdio only.

  • Some premium accelerators need a real-account check.

Full list: docs/known-limitations.md.

License

Apache License 2.0

Available Tools

30 tools
gpu_auth_statusC

Auth snapshots. Mock data are TEST FIXTURES, not a live account.

account reads that account only. There is no automatic rotation.

Inputs: account, provider. Returns: object

gpu_cancel_jobC

Cancel a job. Mock data are TEST FIXTURES, not a live account.

Kaggle's official CLI cannot cancel a running kernel.

Inputs: job_id (required). Returns: object

gpu_doctorB

Local doctor report. Mock data are TEST FIXTURES, not a live account.

Does not execute kaggle or colab. CLI presence is shutil.which.

Inputs: no named parameters. Returns: object

gpu_download_artifactsC

Download artifacts under artifact_root. Mock data are TEST FIXTURES.

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

gpu_get_job_logsC

Tail of the job log. Mock data are TEST FIXTURES, not a live account.

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

gpu_get_job_statusD

Job state. Mock data are TEST FIXTURES, not a live account.

Inputs: job_id (required). Returns: object

gpu_get_quotaB

Quota snapshots. Mock data are TEST FIXTURES, not a live account.

account reads that account only. There is no automatic rotation. refresh drops the per-account quota cache entry before reading.

Inputs: account, refresh, provider. Returns: object

gpu_list_accountsA

List accounts. Mock data are TEST FIXTURES, not a live account.

Credential values are not included. Quota exhaustion does not rotate to another account of the same provider.

Inputs: no named parameters. Returns: object

gpu_list_jobsB

List stored jobs. Mock data are TEST FIXTURES, not a live account.

This does not call a provider and does not submit. limit defaults to 50. Pass null to return every match.

Inputs: limit, state, provider. Returns: object

gpu_list_providersB

List providers. Mock data are TEST FIXTURES, not a live account.

Inputs: no named parameters. Returns: object

gpu_list_resourcesC

Accelerators. Memory is per GPU. Mock data are TEST FIXTURES, not a live account.

account lists that account only. There is no automatic rotation. When quota publishes eligible_gpus, each row includes eligible.

Inputs: account, provider. Returns: object

gpu_recommend_backendA

Recommend a backend without submitting. Mock data are TEST FIXTURES, not a live account.

A premium GPU needs scheduler.allow_premium_gpu plus allow_premium. Colab needs timeout_seconds so the CCU budget can be checked. provider auto lets the scheduler choose. account pins that account and does not rotate on quota. Per-GPU memory is never summed across devices.

Inputs: account, gpu_type, high_mem, provider, +4 more. Returns: object

gpu_reconcile_jobsA

Poll job status. Mock data are TEST FIXTURES, not a live account.

Omit job_ids to poll every active job, including UNKNOWN. Reconcile never submits and never resubmits an ambiguous job.

Inputs: job_ids. Returns: object

gpu_refresh_quotaB

Refresh quota snapshots. Mock data are TEST FIXTURES, not a live account.

Equivalent to gpu_get_quota(..., refresh=True).

Inputs: account, provider. Returns: object

gpu_submit_jobA

Submit a script. Mock data are TEST FIXTURES, not a live account.

provider auto asks the scheduler to choose. A premium GPU needs scheduler.allow_premium_gpu plus allow_premium. high_mem maps to Colab --high-mem (CPU/T4/A100/H100/G4; not L4/TPU) and does not bypass premium guards. Colab needs timeout_seconds so the CCU budget can be checked. Real jobs also require mode: real and allow_real_jobs. idempotency_key returns the existing job instead of submitting again when the spec matches. A different spec is an invalid-input error. deduplicated is true when the existing job is returned. An ambiguous submit is not resubmitted. account pins that account. Quota exhaustion does not rotate to another account. dry_run recommends a backend and does not submit.

Inputs: script_path (required), name, account, dry_run, +8 more. Returns: object

l2kc_auth_statusC

Auth snapshots. Mock data are TEST FIXTURES, not a live account.

account reads that account only. There is no automatic rotation.

Inputs: account, provider. Returns: object

l2kc_cancel_jobB

Cancel a job. Mock data are TEST FIXTURES, not a live account.

Kaggle's official CLI cannot cancel a running kernel.

Inputs: job_id (required). Returns: object

l2kc_doctorC

Local doctor report. Mock data are TEST FIXTURES, not a live account.

Does not execute kaggle or colab. CLI presence is shutil.which.

Inputs: no named parameters. Returns: object

l2kc_download_artifactsC

Download artifacts under artifact_root. Mock data are TEST FIXTURES.

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

l2kc_get_job_logsC

Tail of the job log. Mock data are TEST FIXTURES, not a live account.

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

l2kc_get_job_statusC

Job state. Mock data are TEST FIXTURES, not a live account.

Inputs: job_id (required). Returns: object

l2kc_get_quotaC

Quota snapshots. Mock data are TEST FIXTURES, not a live account.

account reads that account only. There is no automatic rotation. refresh drops the per-account quota cache entry before reading.

Inputs: account, refresh, provider. Returns: object

l2kc_list_accountsB

List accounts. Mock data are TEST FIXTURES, not a live account.

Credential values are not included. Quota exhaustion does not rotate to another account of the same provider.

Inputs: no named parameters. Returns: object

l2kc_list_jobsA

List stored jobs. Mock data are TEST FIXTURES, not a live account.

This does not call a provider and does not submit. limit defaults to 50. Pass null to return every match.

Inputs: limit, state, provider. Returns: object

l2kc_list_providersB

List providers. Mock data are TEST FIXTURES, not a live account.

Inputs: no named parameters. Returns: object

l2kc_list_resourcesC

Accelerators. Memory is per GPU. Mock data are TEST FIXTURES, not a live account.

account lists that account only. There is no automatic rotation. When quota publishes eligible_gpus, each row includes eligible.

Inputs: account, provider. Returns: object

l2kc_recommend_backendA

Recommend a backend without submitting. Mock data are TEST FIXTURES, not a live account.

A premium GPU needs scheduler.allow_premium_gpu plus allow_premium. Colab needs timeout_seconds so the CCU budget can be checked. provider auto lets the scheduler choose. account pins that account and does not rotate on quota. Per-GPU memory is never summed across devices.

Inputs: account, gpu_type, high_mem, provider, +4 more. Returns: object

l2kc_reconcile_jobsA

Poll job status. Mock data are TEST FIXTURES, not a live account.

Omit job_ids to poll every active job, including UNKNOWN. Reconcile never submits and never resubmits an ambiguous job.

Inputs: job_ids. Returns: object

l2kc_refresh_quotaB

Refresh quota snapshots. Mock data are TEST FIXTURES, not a live account.

Equivalent to gpu_get_quota(..., refresh=True).

Inputs: account, provider. Returns: object

l2kc_submit_jobB

Submit a script. Mock data are TEST FIXTURES, not a live account.

provider auto asks the scheduler to choose. A premium GPU needs scheduler.allow_premium_gpu plus allow_premium. high_mem maps to Colab --high-mem (CPU/T4/A100/H100/G4; not L4/TPU) and does not bypass premium guards. Colab needs timeout_seconds so the CCU budget can be checked. Real jobs also require mode: real and allow_real_jobs. idempotency_key returns the existing job instead of submitting again when the spec matches. A different spec is an invalid-input error. deduplicated is true when the existing job is returned. An ambiguous submit is not resubmitted. account pins that account. Quota exhaustion does not rotate to another account. dry_run recommends a backend and does not submit.

Inputs: script_path (required), name, account, dry_run, +8 more. Returns: object

Tool Schema Changelog

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

Loading tool schema changelog…

    TDQS

    C2.6/5.0

    Scored across 30 tools

    Disambiguation1/5

    Every tool has an exact duplicate under a different prefix (gpu_ vs l2kc_), with identical descriptions. An agent cannot determine which of the two identical-looking tools to call, making the set highly ambiguous despite unique underlying functions.

    Naming Consistency3/5

    Within each prefix, tools follow a clear verb_noun pattern (list_providers, submit_job, get_job_status). However, maintaining two parallel prefixes for identical functionality creates an inconsistent naming scheme that is readable but confusing.

    Tool Count2/5

    30 tools is too many for the apparent scope, especially since half are duplicates. There are only about 15 unique operations, so the effective surface is reasonable but inflated to 30 by aliases.

    Completeness4/5

    The tool surface covers provider/account/auth/quota listing, resource listing, job submission, status, logs, artifacts, cancellation, listing, reconciliation, backend recommendation, and doctor checks. Minor gaps like direct job deletion or detail retrieval may exist, but core lifecycle operations are present.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      B
      quality
      D
      maintenance
      Local-first MCP server for controlling Google Colab as a development, shell, file, and training runtime, with tools for notebook editing, GPU acceleration, and file transfer.
      59
      9
      Apache 2.0
    • A
      license
      A
      quality
      D
      maintenance
      MCP server that allocates Google Colab GPU runtimes (T4/L4) and executes Python code on them. Lets any MCP-compatible AI assistant run GPU-accelerated code without local GPU hardware.
      3
      9
      MIT
    • A
      license
      B
      quality
      C
      maintenance
      Lets any MCP-compatible agent use Google Colab or Jupyter runtimes as an execution backend, enabling code execution, notebook management, package installation, hardware introspection, training jobs, and file handling.
      40
      1
      MIT