Skip to main content
Glama

Kaggle MCP Server

Independent Kaggle CLI MCP server with 74 tools (v3.1), including a local experiment ledger.

Track notebook fingerprints, declared dataset versions, parameters, and reported metrics across experiments. Compare runs sharing the same declared evaluation protocol.

Kaggle also offers an official remote MCP server. This community project is independent and is not endorsed by Kaggle or Anthropic. Its distinct addition is a local experiment provenance workflow.

See experiment tools and tutorial and the development roadmap.

python examples/experiment_demo.py  # offline demo; synthetic metrics, no account needed
python -m unittest discover -s tests -v

Works with Claude Desktop, Claude Code, OpenAI Codex CLI, Cursor, Hermes Agent, Windsurf, OpenCode, VS Code MCP, Continue.dev, and any stdio MCP client.

What you can do

Area

Tools

Kernels

search, list mine, status, logs, files, output download, pull/push, init, update, delete, preview, visibility, topics

Datasets

search, list mine, details, files, download, init, upload, version, metadata, status, delete, topics

Competitions

list, files, download, submit, submissions, leaderboard, team-submissions, episodes, replay, logs, pages, topics

Models

list/get/create/update/delete, instances, versions, version files/download, topics

Forums

list forums, list/show topics

Benchmarks

list tasks, list models, task status

Account

quota (GPU/TPU), account info, CLI config

Transports

  • --stdio preferred for agents

  • --port N legacy local HTTP SSE + /rpc; not validated as standard remote MCP. Do not expose it as a hosted service.

Related MCP server: Kaggle MCP Server

Install

git clone https://github.com/mtrakretech/kaggle-mcp.git
cd kaggle-mcp
pip install -r requirements.txt
python kaggle_mcp.py --setup

What it does:

  1. Tells you where to get a token: https://www.kaggle.com/settings → API → Create New Token

  2. Asks for username + API key (key input hidden)

  3. Optionally reuses a downloaded kaggle.json (cwd / Downloads / ~/.kaggle)

  4. Saves:

    • ~/.kaggle/kaggle.json (chmod 600 when possible)

    • project .env (KAGGLE_USERNAME, KAGGLE_KEY, KAGGLE_API_TOKEN)

  5. Validates with kaggle quota

Non-interactive:

python kaggle_mcp.py --setup --username YOUR_USER --key YOUR_KEY
python kaggle_mcp.py --setup --from-json ~/Downloads/kaggle.json
python kaggle_mcp.py --setup --no-env          # only ~/.kaggle/kaggle.json
python kaggle_mcp.py --setup --no-validate    # skip API check

Manual alternatives:

export KAGGLE_USERNAME=your_username
export KAGGLE_KEY=your_api_key
export KAGGLE_API_TOKEN=$KAGGLE_KEY

Or hand-write ~/.kaggle/kaggle.json:

{"username":"your_username","key":"your_api_key"}

Quick test

python kaggle_mcp.py --setup          # first time
python kaggle_mcp.py --list-tools
python kaggle_mcp.py --stdio

Client setup

Replace /ABSOLUTE/PATH/TO/kaggle-mcp/kaggle_mcp.py with your real path.
Copy-paste examples: examples/.

Claude Desktop

%APPDATA%\Claude\claude_desktop_config.json (Windows) / ~/Library/Application Support/Claude/claude_desktop_config.json (macOS):

{
  "mcpServers": {
    "kaggle": {
      "command": "python",
      "args": ["/ABSOLUTE/PATH/TO/kaggle-mcp/kaggle_mcp.py", "--stdio"],
      "env": {
        "KAGGLE_USERNAME": "your_kaggle_username",
        "KAGGLE_KEY": "your_kaggle_api_key",
        "KAGGLE_API_TOKEN": "your_kaggle_api_key"
      }
    }
  }
}

Claude Code / Cursor / Windsurf

Same mcpServers.kaggle JSON shape as above.

Codex CLI (~/.codex/config.toml)

[mcp_servers.kaggle]
command = "python"
args = ["/ABSOLUTE/PATH/TO/kaggle-mcp/kaggle_mcp.py", "--stdio"]

[mcp_servers.kaggle.env]
KAGGLE_USERNAME = "your_kaggle_username"
KAGGLE_KEY = "your_kaggle_api_key"
KAGGLE_API_TOKEN = "your_kaggle_api_key"

Hermes Agent (config.yaml)

mcp_servers:
  kaggle:
    command: python
    args:
      - /ABSOLUTE/PATH/TO/kaggle-mcp/kaggle_mcp.py
      - --stdio
    env:
      KAGGLE_USERNAME: your_kaggle_username
      KAGGLE_KEY: your_kaggle_api_key
      KAGGLE_API_TOKEN: your_kaggle_api_key
    timeout: 180

Use stdio (not HTTP SSE) with Hermes.

OpenCode / VS Code / Continue

See examples/opencode_config.json, examples/vscode_mcp.json, examples/continue_config.yaml.

Tools (74)

Experiments (6)

plan_experiment verify_experiment get_experiment record_experiment_result list_experiments compare_experiments

These local tools work without Kaggle credentials when started with --stdio. See limitations and storage.

Kernels (15)

search_kernels list_my_kernels kernel_status kernel_logs kernel_files kernel_output pull_notebook push_notebook init_kernel update_kernel delete_kernel preview_notebook toggle_kernel_visibility list_kernel_topics show_kernel_topic

Datasets (13)

search_datasets list_my_datasets dataset_details list_dataset_files download_dataset init_dataset upload_dataset update_dataset get_dataset_metadata dataset_status delete_dataset list_dataset_topics show_dataset_topic

Competitions (13)

list_competitions list_competition_files download_competition_data submit_competition list_competition_submissions competition_leaderboard list_team_submissions list_competition_episodes download_competition_replay download_competition_episode_logs list_competition_pages list_competition_topics show_competition_topic

Models (18)

list_models model_details init_model create_model update_model delete_model list_model_instances get_model_instance init_model_instance create_model_instance update_model_instance delete_model_instance list_model_instance_versions list_model_version_files download_model_version create_model_version delete_model_version list_model_topics

Forums / Benchmarks / Account (9)

list_forums list_forum_topics show_forum_topic list_benchmark_tasks list_benchmark_models benchmark_task_status get_quota get_account_info get_config

Historical live test notes (v3.0)

The following are prior maintainer reports, not live verification of v3.1. New v3.1 checks run offline; no Kaggle account actions were performed.

Verified working against real API on this machine:

  • kernels search/list/status/logs/files/pull/preview/output

  • datasets search/list/details/files/metadata/download/topics

  • competitions list/files/leaderboard/pages/topics/team-submissions

  • models list/get/instances/versions

  • forums list/topics, benchmarks list/models, quota, config, init skeletons

Known Kaggle-side soft fails (tool wiring OK; API returns error):

  • dataset_status → 404 on some public datasets

  • list_competition_submissions → 400 if you never entered the competition

  • list_model_version_files / some instance paths → 404 if version ref wrong

  • topic show_* → 429 under rate limit (retry later)

Destructive tools (delete_*, submit_competition, push_notebook, uploads) are implemented but not auto-run in CI-style tests.

Security

  • No hardcoded credentials

  • Env vars or ~/.kaggle/kaggle.json only

  • The experiment ledger stores no credentials. Connected clients can see tool results; review content before sharing.

  • Use stdio. Legacy HTTP is not intended for network exposure.

  • Notebook outputs, uploaded folders, parameters and notes can contain sensitive data; review them before use.

License

MIT — see LICENSE

Available Tools

68 tools
benchmark_task_statusC

Show benchmark task status

Inputs: task (required).

competition_leaderboardC

Show competition leaderboard

Inputs: comp (required), download, page_size, output_dir.

create_modelB

Create model from folder with model-metadata.json

Inputs: folder (required).

create_model_instanceC

Create model instance from folder

Inputs: folder (required).

create_model_versionC

Create new model instance version from folder

Inputs: folder (required), instance_ref (required), version_notes.

dataset_detailsC

Dataset metadata via REST API

Inputs: ref (required).

dataset_statusC

Dataset creation/processing status

Inputs: ref (required).

delete_datasetB

Delete dataset permanently

Inputs: ref (required).

delete_kernelB

Delete a kernel permanently

Inputs: ref (required).

delete_modelC

Delete a model permanently

Inputs: model_ref (required).

delete_model_instanceC

Delete a model instance

Inputs: instance_ref (required).

delete_model_versionC

Delete a model instance version

Inputs: version_ref (required).

download_competition_dataC

Download competition files

Inputs: comp (required), file_name, output_dir.

download_competition_episode_logsC

Download agent logs for a simulation episode

Inputs: episode_id (required), output_dir, agent_index.

download_competition_replayC

Download simulation episode replay

Inputs: episode_id (required), output_dir.

download_datasetC

Download dataset files

Inputs: ref (required), unzip, file_name, output_dir.

download_model_versionC

Download model instance version files

Inputs: version_ref (required), untar, output_dir.

get_account_infoB

Account username + quota snapshot

Inputs: no named parameters.

get_configA

Show kaggle CLI config

Inputs: no named parameters.

get_dataset_metadataC

Download dataset-metadata.json

Inputs: ref (required), output_dir.

get_model_instanceB

Download model-instance-metadata.json

Inputs: instance_ref (required), output_dir.

get_quotaA

Show GPU/TPU quota remaining

Inputs: no named parameters.

init_datasetC

Create dataset-metadata.json skeleton

Inputs: folder (required).

init_kernelC

Create kernel-metadata.json skeleton

Inputs: folder (required).

init_modelC

Initialize model-metadata.json in folder

Inputs: folder (required).

init_model_instanceC

Init model-instance-metadata.json

Inputs: folder (required).

kernel_filesC

List kernel output files (metadata)

Inputs: ref (required), page_size.

kernel_logsC

Get kernel execution logs

Inputs: ref (required).

kernel_outputC

Download kernel output files

Inputs: ref (required), output_dir, file_pattern.

kernel_statusC

Check kernel run status

Inputs: ref (required).

list_benchmark_modelsB

List available benchmark models

Inputs: no named parameters.

list_benchmark_tasksC

List your benchmark tasks

Inputs: status, name_regex.

list_competition_episodesC

List simulation episodes for a submission

Inputs: submission_id (required).

list_competition_filesC

List competition data files

Inputs: comp (required), page_size.

list_competition_pagesC

List competition pages (rules/description/evaluation)

Inputs: comp (required), content, page_name.

list_competitionsD

List competitions

Inputs: group, limit, search, sort_by, +1 more.

list_competition_submissionsB

List your submissions for a competition

Inputs: comp (required), page_size.

list_competition_topicsC

List competition forum topics

Inputs: comp (required), page, sort_by.

list_dataset_filesC

List files in a dataset

Inputs: ref (required), page_size.

list_dataset_topicsC

List dataset discussion topics

Inputs: ref (required), search, sort_by, page_size.

list_forumsB

List Kaggle forums

Inputs: no named parameters.

list_forum_topicsC

List topics in a forum or global search

Inputs: forum, search, sort_by, category, +1 more.

list_kernel_topicsB

List discussion topics on a kernel

Inputs: ref (required), search, sort_by, page_size.

list_model_instancesC

List model instances/variations for owner/model

Inputs: model_ref (required), page_size.

list_model_instance_versionsC

List versions for a model instance

Inputs: instance_ref (required), page_size.

list_modelsC

List / search Kaggle models

Inputs: limit, owner, search, sort_by.

list_model_topicsC

List model discussion topics

Inputs: model_ref (required), page_size.

list_model_version_filesB

List files in a model instance version

Inputs: version_ref (required), page_size.

list_my_datasetsC

List your datasets

Inputs: page, limit.

list_my_kernelsC

List your Kaggle notebooks

Inputs: page, limit, sort_by.

list_team_submissionsB

List public submissions for a team ID

Inputs: team_id (required).

model_detailsC

Get model details

Inputs: model_ref (required).

preview_notebookB

Preview first N cells of a notebook

Inputs: ref (required), max_cells.

pull_notebookC

Download notebook source (.ipynb)

Inputs: ref (required), output_dir, with_metadata.

push_notebookC

Upload notebook and run on free GPU/TPU

Inputs: path (required), gpu, tpu, name, +5 more.

search_datasetsC

Search Kaggle datasets

Inputs: mine, page, user, limit, +3 more.

search_kernelsB

Search public Kaggle notebooks/kernels

Inputs: query (required), user, limit, dataset, +4 more.

show_competition_topicC

Show competition topic thread

Inputs: topic_ref (required).

show_dataset_topicC

Show dataset topic thread

Inputs: topic_ref (required).

show_forum_topicC

Show forum topic thread

Inputs: topic_ref (required).

show_kernel_topicC

Show a kernel discussion topic

Inputs: topic_ref (required).

submit_competitionC

Submit predictions file or kernel to a competition

Inputs: comp (required), file, kernel, message, +1 more.

toggle_kernel_visibilityC

Make kernel public or private

Inputs: ref (required), make_public.

update_datasetC

Create new dataset version

Inputs: dir_path (required), version_notes, delete_old_versions.

update_kernelC

Update kernel metadata via pull+push

Inputs: ref (required), enable_gpu (required), enable_tpu (required), is_private (required), +1 more.

update_modelC

Update model metadata from folder

Inputs: folder (required).

update_model_instanceC

Update model instance metadata from folder

Inputs: folder (required).

upload_datasetC

Create a new dataset from a folder

Inputs: dir_path (required), name, public, subtitle, +1 more.

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 68 tools

    Disambiguation3/5

    The verb_noun structure separates most actions, but several pairs blur together: kernel_files/kernel_output, dataset_details/get_dataset_metadata, model_details/get_model_instance, and get_quota/get_account_info all require close reading. The many model/instance/version lifecycle variants are easy to misselect without careful attention to the resource level.

    Naming Consistency4/5

    Tool names mostly follow a consistent snake_case verb_noun convention (list_, create_, update_, delete_, download_, init_). Minor inconsistencies exist: kernel and notebook are used interchangeably for the same resource, competition_leaderboard and dataset_details lack a verb, and update_dataset means 'new version' while update_model means metadata-only update.

    Tool Count1/5

    68 tools is far beyond a reasonable MCP surface and exceeds the 50+ threshold for an extreme count. While the tools cover distinct Kaggle domains, the server would be much more usable split into separate dataset, kernel, competition, and model servers.

    Completeness5/5

    The tool surface is exhaustive across Kaggle's main workflows: dataset, kernel, and model CRUD/lifecycle operations, competition submission flows, discussion forums, and account/quota information. Core workflows have no obvious dead ends, and the high count is largely due to genuinely broad domain coverage.

    Maintenance

    ActivityMaintained
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers