docs/kaggle_mcp_setup.md

# Kaggle MCP Setup — Connecting Claude Desktop to Your Kaggle Account

*Audience: anyone on Sahel-Voice-Lab who wants a Kaggle-aware Claude on their own machine*
*Last updated: 2026-04-20*

## What this is, and what it isn't

The Kaggle MCP (Model Context Protocol) is a small server that wraps the Kaggle API and exposes it as tools a Claude client can call. Once set up, you can ask Claude things like "what's the status of my training kernel" or "find Bambara datasets on Kaggle" and it will actually reach Kaggle and answer with live data, rather than guessing.

**Important context:** the MCP runs on your **local machine** and connects to a **local Claude client** — specifically Claude Desktop. It does **not** plug into this Cowork session. Cowork only uses MCPs that are in its registry, and Kaggle isn't there yet. So this setup gives you a parallel, Kaggle-aware Claude in your desktop app; it doesn't change what's available in Cowork.

If you haven't installed Claude Desktop yet, that's step zero — grab it from [claude.ai/download](https://claude.ai/download) and sign in with the same account you already use.

## Which implementation to install

Multiple implementations exist. Kaggle has their own page at [kaggle.com/docs/mcp](https://www.kaggle.com/docs/mcp), plus several community ports on GitHub:

- `54yyyu/kaggle-mcp` — covers dataset, competition, **and kernel** operations. Recommended for Sahel-Voice-Lab because we care about kernel operations (pushing, monitoring, pulling results), not just dataset search.
- `Dishant27/kaggle-MCP` — competition-focused. Less relevant for us.
- `KrishnaPramodParupudi/kaggle-mcp-server` — also Claude Desktop-oriented; feature-wise similar to `54yyyu/kaggle-mcp`.

Start with `54yyyu/kaggle-mcp`. Cross-check against the official Kaggle docs page for whatever they're currently recommending — the MCP landscape shifts every few months.

## Prerequisites

- Python 3.10 or newer
- `git` installed
- A Kaggle account
- Your Kaggle API credentials already set up at `~/.kaggle/kaggle.json` with mode 600 (if not, see the notebook collaboration guide or the short version below)
- Claude Desktop installed and opened at least once

Quick credentials sanity check:

```bash
ls -l ~/.kaggle/kaggle.json
# expect: -rw------- ... kaggle.json
```

If missing: Kaggle → Settings → API → **Create New API Token**, move `kaggle.json` to `~/.kaggle/kaggle.json`, `chmod 600 ~/.kaggle/kaggle.json`.

## Step-by-step setup

### Step 1 — Install the MCP server

Clone into a persistent folder (not `/tmp`):

```bash
mkdir -p ~/tools
cd ~/tools
git clone https://github.com/54yyyu/kaggle-mcp.git
cd kaggle-mcp
```

Check the repo's README for the exact install command. It will be one of:

```bash
pip install -e .
# or
uv pip install -e .
# or
pip install -r requirements.txt
```

Strongly consider using a dedicated virtualenv or conda env so the MCP's dependencies don't collide with Sahel-Voice-Lab's. Example:

```bash
python -m venv ~/tools/kaggle-mcp/.venv
source ~/tools/kaggle-mcp/.venv/bin/activate
pip install -e .
```

Confirm the server launches:

```bash
python -m kaggle_mcp --help
# or whatever entry point the README names
```

If that errors, stop and fix — don't move on until this command responds cleanly.

**Take note of the absolute Python path** you used, because Claude Desktop will need it:

```bash
which python
# e.g. /Users/broulaye/tools/kaggle-mcp/.venv/bin/python
```

### Step 2 — Locate Claude Desktop's config file

Platform-specific:

- **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
- **Linux:** `~/.config/Claude/claude_desktop_config.json`

If the file doesn't exist, create it with an empty object `{}`.

### Step 3 — Add the Kaggle MCP to the config

Open the file and add an `mcpServers` section. Example (substitute the absolute Python path from Step 1, and confirm the `args` against the repo's README — that's the most commonly-differing piece):

```json
{
  "mcpServers": {
    "kaggle": {
      "command": "/Users/broulaye/tools/kaggle-mcp/.venv/bin/python",
      "args": ["-m", "kaggle_mcp"],
      "env": {
        "KAGGLE_USERNAME": "your_kaggle_username",
        "KAGGLE_KEY": "your_kaggle_api_key"
      }
    }
  }
}
```

Two frequent gotchas:

1. **`command` must be an absolute path** to the Python that has `kaggle_mcp` installed. If you used a virtualenv or conda env, don't rely on `"python"` alone — Claude Desktop launches the system Python, which won't find the package.
2. **`KAGGLE_USERNAME` / `KAGGLE_KEY`** come from your `~/.kaggle/kaggle.json`. Some implementations read that file automatically and you can omit the `env` block; the README will say.

Save the file.

### Step 4 — Fully restart Claude Desktop

Not just close the window — **quit completely** (⌘Q on macOS, right-click tray icon → Quit on Windows). Reopen. MCP servers start with the client.

### Step 5 — Verify it loaded

In a new Claude Desktop conversation, try:

```
Using the Kaggle MCP, list my recent kernels.
```

If it works, Claude will call the MCP and return your kernels (including `sahel-kaggle-master-trainer`).

If it doesn't, open **Settings → Developer → Open Logs** and look for lines mentioning `kaggle` or `mcp`. Common failures:

- `ModuleNotFoundError: kaggle_mcp` — `command` points to the wrong Python. Paste the absolute path from `which python` inside your virtualenv.
- `401 Unauthorized` — credentials missing or wrong. Test first with `kaggle kernels list --mine` in a terminal; if that fails, the MCP will fail the same way.
- `spawn ENOENT` — `command` needs to be a full path, not just `"python"`.
- MCP starts but tools are missing — check the repo's README; the tool list can evolve.

## First useful things to ask it, for Sahel-Voice-Lab

Once it's live, high-leverage uses for our project:

- **Dataset discovery.** "Find Bambara or Fula ASR datasets on Kaggle I haven't used yet." Feeds Stage C eval-set work.
- **Kernel monitoring.** "What's the status of `ous-sow/sahel-kaggle-master-trainer`? Show the last run's log tail." Replaces tab-switching.
- **Dataset download into the repo.** "Download RobotsMali Jeli-ASR to `~/projects/sahel-agri-voice/data/raw/`."
- **Prior-art scans.** "Show me public Kaggle notebooks using `openai/whisper-large-v3-turbo` for African languages."

## Use with care

- **Pushing training kernels.** Technically possible, but `kaggle kernels push` replaces the shared kernel on Kaggle's side. You want human review and coordination with your collaborator before that happens. Use the CLI workflow from `docs/notebook_collaboration.md` for pushes; use the MCP for reads and discovery.
- **Anything that costs GPU hours.** The 30-hour weekly quota still applies; the MCP doesn't know your budget.
- **Credentials in the config file.** `claude_desktop_config.json` sits in your home directory in plaintext. If your machine is shared, treat the `env` block as a secret; prefer the MCP implementation that reads `~/.kaggle/kaggle.json` directly (so nothing sensitive lands in the config file).

## What the MCP won't do

- It won't debug a T4 training crash interactively. You can push and watch, but the crash itself still lives in Kaggle's logs, eyeballed by a human.
- It won't raise your GPU quota.
- It won't help with merge conflicts or Kaggle's rate limits.
- It won't work in this Cowork session — only Claude Desktop (or Claude Code, if you've set up MCP there separately).
- It doesn't replace the `kaggle` CLI; it's a friendlier, conversational interface to the same API.

## Troubleshooting summary

| Symptom | Likely cause | Fix |
|---|---|---|
| Claude says "I don't have a Kaggle tool" | MCP didn't start | Check Developer Logs; fix `command` path |
| `ModuleNotFoundError: kaggle_mcp` | Wrong Python interpreter | Use absolute path to virtualenv Python |
| `401 Unauthorized` | Bad/missing credentials | Re-test with `kaggle kernels list --mine` in terminal |
| `spawn ENOENT` | Relative command path | Absolute path in `command` |
| Tool names don't match the docs | Implementation changed | Re-read the repo's README; align your prompts |
| Works once, then stops | Claude Desktop not fully quit on last restart | Fully quit, reopen |

## TL;DR

Install `54yyyu/kaggle-mcp` locally into a virtualenv, make sure `~/.kaggle/kaggle.json` is present, point Claude Desktop's `claude_desktop_config.json` at the virtualenv's Python, fully quit and reopen. Use for reads and discovery; keep the CLI for kernel pushes. Won't work in Cowork — Claude Desktop only.