kctx

Give Claude the full context of any Kaggle competition in one command: the overview, evaluation metric, rules, data description, top discussions (winning solution write-ups first) and top public notebooks.

Install

kctx is on PyPI. Pick any one of these; each gives you the kctx command (Python 3.11+):

pip install kctx                 # plain pip (inside a virtualenv is best)
uv tool install kctx             # uv: isolated install, recommended
pipx install kctx                # pipx: isolated install
uvx kctx                         # uv: run it once without installing

No Python or uv yet? This one-liner installs uv (which fetches Python), installs kctx and starts it:

curl -fsSL https://raw.githubusercontent.com/vks-g/kctx/main/install.sh | sh

To upgrade later: pip install -U kctx, uv tool upgrade kctx or pipx upgrade kctx.

Quick start

Run kctx. It asks you a few questions right in your terminal. Move with the arrow keys; in multi-choice questions, enter (or space) ticks an option and you finish by picking Continue:

✓ Kaggle: signed in as you
? Competition URL or search: titanic
  Titanic - Machine Learning from Disaster
  Metric: Categorization Accuracy  ·  Deadline: 2030-01-01 00:00 UTC  ·  Teams: 10,307
? How should Claude get the context? (↑/↓ move · enter or space to tick · then pick Continue)
   [x] Workspace folder  CLAUDE.md + overview, rules, data, discussions, code
   [x] Claude skill  loads automatically when you work on this competition
   [ ] MCP server  Claude calls tools for rules, discussions, notebooks, what's new
 ❯ Continue →
? Create the workspace folder in: /Users/you/kaggle
Fetching Titanic - Machine Learning from Disaster
  ✓ overview     5 pages
  ✓ rules        found
  ✓ data files   3 files
  ✓ discussions  16 topics (1 solution write-ups)
  ✓ notebooks    5 notebooks
  ✓ leaderboard  top 20
✓ Workspace folder: /Users/you/kaggle/titanic

If you have no Kaggle credentials yet, it first offers a browser login or lets you paste an API token.

You can paste a competition URL or slug, or type a word or two to search Kaggle (e.g. gemma) and pick a match from the arrow-key list. If none of the matches is right, choose search again.

Skip the URL question by passing it: kctx https://www.kaggle.com/competitions/titanic (or curl … | sh -s -- <url> with the one-liner).

Which mode should I pick?

The modes combine well. A typical setup is the workspace folder (for your code) plus the MCP server (to keep up with the forum).

1 · Workspace folder

titanic/
├── CLAUDE.md / AGENTS.md   key facts + a map of everything below (auto-loaded by Claude Code)
├── CONTEXT.md              everything in one token-budgeted file (default 50k tokens)
├── overview/               description, evaluation, timeline, prizes, FAQ, leaderboard, metadata.json
├── rules/rules.md
├── data/
│   ├── README.md           data description + file list + how to get it
│   ├── download.sh         you run this after accepting the rules; data lands in data/raw/
│   └── raw/                (empty, git-ignored)
├── discussions/            INDEX.md, solutions/ (winning write-ups), topics/ (top comments by votes)
└── code/                   INDEX.md, one .md per notebook (outputs stripped, attributed), notebooks/*.ipynb

The data is never downloaded for you. Competition rules usually forbid redistributing it, and it can be many GB. data/download.sh fetches it with your own account once you've accepted the rules.

2 · Claude skill

kctx generates a per-competition skill, kaggle-<slug>, laid out for progressive disclosure:

kaggle-titanic/
├── SKILL.md       frontmatter (the ~100 tokens Claude always sees) + key facts + a file map
└── references/    overview/, rules/, data/, discussions/, code/ (read one file at a time)

Only the name and description sit in context until the skill is relevant, so dozens of discussions and notebooks cost nothing until Claude needs them. You choose where it goes:

• ~/.claude/skills/: every project (default)
• <project>/.claude/skills/: one project, can be committed and shared with teammates
• zip: upload at claude.ai → Settings → Capabilities → Skills, to use it in the web app or Desktop

To use it in Claude Code, type /kaggle and pick /kaggle-<slug>, or just ask about the competition ("are external models allowed?") and Claude loads it on its own.

3 · MCP server: no infrastructure needed

kctx mcp is a local stdio server. Claude Code or Claude Desktop starts it on your machine when needed. It uses your own ~/.kaggle credentials and a disk cache (~/.cache/kctx). There is no hosted server, no database and no cost.

It also exposes a kaggle://{competition}/{section} resource and a start-competition prompt. kctx registers the server for you (Claude Code, Claude Desktop, or a project .mcp.json; check it with /mcp in Claude Code). To do it by hand:

claude mcp add --scope user kctx -- kctx mcp

For Claude Desktop, add this to claude_desktop_config.json, using the absolute path to kctx because Desktop doesn't see your shell PATH:

{ "mcpServers": { "kctx": { "command": "/Users/you/.local/bin/kctx", "args": ["mcp"] } } }

A hosted MCP (for claude.ai on the web or mobile) would need a server and safe handling of each user's Kaggle token. It's on the roadmap, but you don't need it for Claude Code or Desktop.

Claude Code plugin

To get the generic kctx skill and the MCP server in one step:

/plugin marketplace add vks-g/kctx
/plugin install kctx@kctx

Headless CLI

Everything the prompts do is also a command, for scripts, CI and agents:

kctx fetch <url|slug> --mode folder,skill,mcp [--out DIR] [--skill-scope user|project|zip]
                      [--mcp-target claude-code,claude-desktop,project,print]
                      [--discussions 15] [--comments 10] [--notebooks 5] [--budget 50000] [--refresh]
kctx refresh [workspace-folder|slug]   # re-fetch; writes WHATS_NEW.md
kctx search "llm"                      # find competitions
kctx login [--token …]                 # connect your Kaggle account
kctx mcp [--competition <slug>]        # run the MCP server (Claude does this for you)

What gets fetched, and how

Everything comes from the official Kaggle API (the same one the kaggle CLI uses), called with your own credentials. There is no HTML scraping.

• Overview: metadata (metric, deadlines, team and submission limits, code-competition flag) plus every competition page.
• Rules: the full rules page. The key-facts card quotes the external-data clause word for word, never paraphrased.
• Data: the data-description page plus the file list with sizes.
• Discussions: the top topics. "Nth place solution" write-ups come first, then pinned host posts. Each topic keeps its top comments by votes (low-signal "great work!" replies are dropped).
• Code: the top public notebooks by votes, with Kaggle Learn exercises filtered out. Outputs are stripped and every notebook is attributed; public Kaggle notebooks are Apache 2.0 by default.
• Leaderboard: the top 20 on the public leaderboard.

kctx is not affiliated with Kaggle. Follow each competition's rules, especially on sharing data and code.

Contributing

Contributions are welcome, from bug reports to new features. To get started:

• Read CONTRIBUTING.md. It covers dev setup, the ground rules and how PRs are reviewed.
• Look for issues labelled good first issue or help wanted.
• Ask questions and float ideas in Discussions.
• Report security problems privately (see SECURITY.md).

Everyone taking part follows the Code of Conduct.

git clone https://github.com/vks-g/kctx && cd kctx
uv sync
uv run pytest            # offline: synthetic fixtures, no Kaggle calls
uv run ruff check src tests && uv run ruff format --check src tests
uv run kctx              # the step-by-step prompts, from your checkout

Roadmap

• Engine + headless CLI
• Step-by-step terminal prompts launched by curl … | sh
• Workspace folder, Claude skill, local MCP server
• Claude Code plugin
• PyPI release (uvx kctx)
• Website with docs and a short install URL
• Windows installer (install.ps1), competition search inside the prompts, an optional hosted MCP

License

MIT