- JavaScript 100%
| Filename | Latest commit message | Latest commit date |
|---|---|---|
|
All checks were successful
CI / check (push) Successful in 22s
20/20 live tool checks passed against Kaggle CLI 2.2.5 with OAuth. v0.1.1 is on the Forgejo registry and its npmjs stage awaits 2FA approval (#5); the running web profile still needs a restart to load 0.1.1. |
||
| .forgejo/workflows | ||
| devops | ||
| docs | ||
| lib | ||
| locale | ||
| scripts | ||
| test | ||
| .gitignore | ||
| AGENTS.md | ||
| CHANGELOG.md | ||
| cordis.patch.yml | ||
| icon.svg | ||
| input | ||
| LICENSE | ||
| LOG.md | ||
| package.json | ||
| README.md | ||
| TASKS.md | ||
dsh-kaggle
Agent-native Kaggle tools for DeepSeek Harness: search and download datasets, read competitions and leaderboards, pull/push notebooks, inspect models, browse forums — plus an optional adapter for Kaggle's official MCP server.
Status: 0.1.1. 31 native
kaggle_*tools over the Kaggle CLI (2.2.x) and two MCP diagnostics; the optional Kaggle MCP adapter is off by default because the server is beta. Live-verified against Kaggle CLI 2.2.5 with OAuth (20/20 read-only checks); CI tests stay offline.
Why
Kaggle's CLI is the workhorse behind projects like ml-lab/LinA,
ml-lab/tardits and ml-lab/hijack, but an agent driving it spends context on
shell syntax, progress bars, pagination, Next Page Token preambles, CSV/JSON
label quirks, and publishes that exit 0 after failing. Kaggle also ships a
remote MCP server (https://www.kaggle.com/mcp) that covers interactive notebook
sessions, benchmarks and write-ups — but with nested protobuf-style requests and
per-endpoint auth.
dsh-kaggle turns both into typed tools:
- CLI-first, no Python import in the Host: the plugin spawns
kaggle, injects the token through the environment, parses JSON defensively, confines every download to the session workspace, and returns{ok, data | error}. - Optional MCP adapter: opt in to register the server's tools as
mcp__kaggle__*for the surfaces the CLI does not cover.
Tool surface
| Area | Tools |
|---|---|
| Diagnostics | kaggle_plugin_info, kaggle_mcp_status, kaggle_mcp_refresh |
| Search | kaggle_search (competitions, datasets, notebooks, models, users, discussions, benchmarks) |
| Datasets | kaggle_datasets_list, kaggle_dataset_files, kaggle_dataset_status, kaggle_dataset_download, kaggle_dataset_create, kaggle_dataset_version, kaggle_dataset_init |
| Competitions | kaggle_competitions_list, kaggle_competition_files, kaggle_competition_download, kaggle_competition_leaderboard, kaggle_competition_submissions, kaggle_competition_submit, kaggle_competition_pages |
| Notebooks | kaggle_kernels_list, kaggle_kernel_pull, kaggle_kernel_push, kaggle_kernel_status, kaggle_kernel_logs, kaggle_kernel_output, kaggle_kernel_files |
| Models | kaggle_models_list, kaggle_models_files, kaggle_model_download, kaggle_models_get |
| Forums | kaggle_forums_list, kaggle_forum_topics, kaggle_forum_topic |
| Quota | kaggle_quota |
List tools return a page of rows plus next_page_token; downloads stream to disk
and return a manifest (path, files, bytes, total_files, up_to_date).
Install
Prerequisites:
- the Kaggle CLI (
pipx install kaggleoruv tool install kaggle, Python ≥ 3.11; on Python 3.14 the PyPI metadata omitssix, so useuv tool install kaggle --with six). A barecliBin: kaggleis also looked up in~/.local/binand the uv/pipx tool directories, because the Host's systemd PATH may not include them; - Kaggle credentials:
kaggle auth login(OAuth), or a token (KGAT…) in~/.kaggle/access_token/KAGGLE_API_TOKEN, or a legacy~/.kaggle/kaggle.json.
Install the plugin from the Forgejo registry:
# Forgejo registry
dsh plugin --profile web add \
--registry https://git.pvlb.dev/api/packages/dsh-plugins/npm/ \
dsh-kaggle@0.1.1
# or from npmjs
dsh plugin --profile web add dsh-kaggle@0.1.1
Restart the profile if the Plugin Manager reports restart-required, then call
kaggle_plugin_info.
Auth
The plugin adds one credential source in front of the CLI's own login: the DSH
credential ref KAGGLE_API_TOKEN (authMode: auto by default). When it
resolves, the token is injected as the child's KAGGLE_API_TOKEN environment
variable — never as an argument and never into a tool result. When it does not,
the CLI's OAuth login or token file is used unchanged.
kaggle_plugin_info reports which sources exist (booleans only) and never a
token value. Store a token in DSH Settings → Credentials if you prefer the
credential store over ~/.kaggle; do not paste it into chat.
MCP (beta)
Off by default. Enable it in the dsh-kaggle row config:
mcpEnabled: true
mcpAuthMode: auto # auto | bearer | none
mcpTokenEnv: KAGGLE_API_TOKEN
mcpTools: [] # optional allowlist globs, e.g. ["search_*", "get_*"]
mcpExcludeTools: []
kaggle_mcp_status shows the connection, registered tools and last error;
kaggle_mcp_refresh re-lists the server's tools and swaps the registered set
without a plugin release. auto connects anonymously when no token is stored —
public search/topic tools work that way; notebook sessions, benchmarks and
quota need a KGAT token. Upstream tools keep their { request: {…} } schemas,
so prefer the native kaggle_* tools for everyday work.
Safety
- Writes (dataset/notebook/model publish, competition submissions) name an exact target; the tool descriptions tell the agent to confirm with the operator first. There is no delete tool and no auto-submit in 0.1.0.
- Tokens are redacted from every captured stream and never logged.
- Downloads and uploads must stay inside the session workspace;
.., absolute escapes and missing files are rejected before the CLI runs. - The CLI's exit code is not trusted for writes:
Dataset creation error: …,Kernel push error: …andSubmission failedwith exit 0 becomeupload_failedwith the redacted tail. - Tests are offline against a fake CLI. No test touches Kaggle or the network.
Errors
| Code | Meaning |
|---|---|
invalid_input |
bad ref/flag/page size, missing metadata file, missing path |
path_refused |
a path escaped the session workspace |
cli_missing |
kaggle not found (install the CLI or set cliBin) |
cli_auth |
Kaggle auth required or rejected |
cli_config |
the CLI could not create its config directory |
cli_timeout |
the command exceeded its wall clock |
cli_parse |
output was not the expected JSON (reported, never guessed) |
forbidden / not_found / rate_limited |
mapped HTTP failures, with hints |
download_failed / upload_failed |
write/transfer failure (including exit-0 traps) |
mcp_disabled / mcp_auth / mcp_unavailable |
optional MCP adapter states |
Configuration
cliBin, authMode, credentialRef, configDir, downloadRoot, pageSize,
commandTimeoutMs, downloadTimeoutMs, maxOutputBytes, noWarn and the
mcp* fields. Defaults are safe for config: {}; see kaggle_plugin_info for
the effective values.
Development
git clone git@git.pvlb.dev:dsh-plugins/dsh-kaggle.git
cd dsh-kaggle
node scripts/dev-link-dsh.mjs
npm test # offline unit/integration tests
npm run check # syntax + tests
npm pack --dry-run # published file list
# opt-in live checks (never in CI)
KAGGLE_LIVE_SMOKE=1 node scripts/smoke-live.mjs # CLI runner probes
KAGGLE_LIVE_SMOKE=1 node scripts/smoke-tools-live.mjs # all read-only tools
Research and design: docs/kaggle-cli.md,
docs/kaggle-mcp.md, docs/design.md,
docs/roadmap.md, docs/releasing.md.
House rules: AGENTS.md.
License
Apache-2.0 — see LICENSE. The Kaggle CLI is Apache-2.0; Kaggle's
service is governed by its own terms.