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 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, 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:

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):

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:

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:

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

Confirm the server launches:

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:

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):

{
  "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.