Kaggle-MCP-Agent

v0.1 — Drive Kaggle notebooks end-to-end from an AI agent (or your CLI) through a local stdio MCP (Model Context Protocol) server. No Kaggle OAuth dance required — just a KGAT_... API token from your Kaggle settings.

open  ->  edit  ->  save (v2)  ->  run  ->  monitor  ->  fetch logs  ->  summarise

This is the basic version. Later we'll add GPU / TPU / internet-enabled runs and richer run summarisation. Multi-agent orchestration (a separate "Kaggle Grandmaster Agent" repo) comes later.

---

Why this exists

Kaggle publishes an MCP server (kaggle-mcp-server), but the official remote endpoint (https://www.kaggle.com/mcp) requires OAuth 2.0 for any tool execution — initialize / tools/list work with a static token, but tools/call returns isError: true. The OAuth flow is awkward to set up locally (no stable Python OAuth client, browser-redirect setup breaks on Windows, etc.).

This repo uses the community kaggle-mcp-server package as a local stdio process instead. The same static KGAT_... token you generate at https://www.kaggle.com/settings works there because the server talks to Kaggle's private REST API on your behalf — no OAuth needed. This is free, scriptable, and works on Windows / macOS / Linux.

What v0.1 can do today

• ✅ Read a private notebook's source (kernel_pull)
• ✅ Edit code cells (replace / insert / text-replace) and serialise back to .ipynb JSON
• ✅ Update an existing notebook as a new version (v1 -> v2 -> ...) — via a small kagglesdk-direct helper that works around the community MCP server's kernel_push slug bug (see below)
• ✅ Poll the run to COMPLETE / ERROR (kernel_session_status)
• ✅ Fetch run output files (kernel_session_output)
• ✅ Run end-to-end from the CLI (python -m kaggle_mcp_agent.run full ...) OR natively from an opencode AI agent session (all kaggle_* tools auto-loaded)

Known limitations (v0.1)

• The community MCP kernel_push tool does not send the slug field when saving a notebook. As a result, calling it to update an existing notebook returns 409 Conflict (Kaggle thinks you're creating a new notebook with a duplicate title). Kaggle-MCP-Agent ships a kagglesdk-direct save_notebook_version() helper that sets req.slug, cleanly creating a new version instead. This is a real upstream bug worth fixing in kaggle-mcp-server.
• Only notebook (ipynj) kernels are exercised end-to-end in v0.1; script kernels parse correctly but the save path is untested.
• GPU / TPU / internet-enabled saves are not yet first-class CLI flags (kagglesdk supports them; we'll add them in v0.2).
• No multi-agent orchestration, memory, or experiment tracking — by design.

---

Quick start

1. Install

# Clone this repo:
git clone https://github.com/Shubhojit2000/Kaggle-MCP-Agent.git
cd Kaggle-MCP-Agent

# Install runtime + dev deps (Python >= 3.10):
pip install -r requirements.txt
pip install -r requirements-dev.txt   # tests only

# Install the community kaggle-mcp-server + kagglesdk (one time):
pip install --user kaggle-mcp-server kagglesdk "mcp==1.29.0"

2. Get a Kaggle API token

1. Open https://www.kaggle.com/settings.
2. Scroll to API -> Generate New Token. It begins with KGAT.
3. Save it locally — never commit it.

3. Configure

Copy .env.example to .env and fill in your token:

cp .env.example .env
# edit .env:
#   KAGGLE_API_TOKEN=KGAT_your_real_token_here
#   KAGGLE_USERNAME=your_kaggle_username

If kaggle-mcp-server is NOT on your PATH (or you want to point at a specific binary), also set in .env:

KAGGLE_MCP_SERVER_EXE=/full/path/to/kaggle-mcp-server   # or .exe on Windows

4. Use it

Option A — From the CLI

# Read a notebook's source:
python -m kaggle_mcp_agent.run pull shubhojitnaskar/mcpnotebook

# List its code cells:
python -m kaggle_mcp_agent.run list-cells shubhojitnaskar/mcpnotebook

# Get the latest run status:
python -m kaggle_mcp_agent.run status shubhojitnaskar/mcpnotebook

# Full workflow: read -> apply edits -> save as v2 -> monitor -> fetch logs:
python -m kaggle_mcp_agent.run full shubhojitnaskar/mcpnotebook --edits examples/edits.json

Edits JSON format

[
  {"op": "replace_code_cell", "index": 0, "source": "print('edited')"},
  {"op": "insert_code_cell",  "index": 1, "source": "print(2)"}
]

Operations:

• replace_code_cell — replace the source of code cell at index
• insert_code_cell — insert a new code cell BEFORE index

Option B — From an opencode AI agent

With opencode.json (see examples/opencode.example.json) in your project directory, all kaggle_* tools become natively callable from your opencode prompts. After putting opencode.json in place and starting opencode:

"Read shubhojitnaskar/mcpnotebook, add print(1) below the existing HF token line in the first code cell and a new print(2) cell after it, save as v2, monitor the run, and fetch the logs."

OpenCode will itself call kaggle_kernel_pull, build the new .ipynb JSON, push (using the v0.1 slug-bug workaround), poll kaggle_kernel_session_status, and kaggle_kernel_session_output for you.

⚠️ Within opencode, the kaggle_kernel_push tool only creates notebooks (it can't push v2 of an existing one due to the slug bug). For updating an existing notebook from an agent prompt, ask it to run the v0.1 helper:

from kaggle_mcp_agent.push import save_notebook_version
save_notebook_version(slug="owner/slug", title="...", text=ipynb_json, ...)

---

Project layout

Kaggle-MCP-Agent/
├── src/kaggle_mcp_agent/
│   ├── __init__.py         # public API exports
│   ├── config.py           # env-driven Settings + token resolution
│   ├── local_mcp.py        # minimal stdio MCP JSON-RPC client (cross-platform)
│   ├── tools.py            # per-tool wrappers over the local kaggle-mcp-server
│   ├── push.py             # kagglesdk-direct save_notebook_version (slug workaround)
│   ├── notebook_utils.py   # parse / edit / re-serialise .ipynb + script sources
│   └── run.py              # CLI: python -m kaggle_mcp_agent.run ...
├── tests/
│   ├── conftest.py
│   ├── test_config.py       # token resolution priority (offline)
│   ├── test_local_mcp.py    # MCP isError handling (offline, faked stdio)
│   ├── test_notebook_utils.py  # .ipynb parse/edit/round-trip (offline)
│   └── test_push.py         # save_notebook_version sets slug (offline, faked kagglesdk)
├── examples/
│   ├── edits.json          # sample edits file
│   └── opencode.example.json  # opencode.json template (no secrets)
├── docs/
│   └── AUTH.md             # full auth history (what works, what doesn't)
├── .env.example
├── .gitignore
├── pyproject.toml
├── requirements.txt
├── requirements-dev.txt
├── LICENSE                 # MIT
└── README.md

---

Tests

# Offline tests run anywhere, no Kaggle token needed:
python -m pytest tests/ -v

All tests are offline and use fakes / mocks — there is no live Kaggle network access in CI. To exercise the live flow against your own Kaggle account, see the examples/ snippets and docs/AUTH.md.

---

Security

• Never commit your KGAT_... token. .env is in .gitignore. The committed opencode.example.json / .env.example deliberately contain placeholders only.
• If you leak a token (paste in chat, push to a public repo), regenerate at https://www.kaggle.com/settings -> API -> Expire / Generate New Token, and update .env.
• Treat any Kaggle token like a password — it carries your account's Kaggle permissions (read private notebooks, push new versions, submit to competitions, etc.).

---

Contributing

Bug reports and PRs welcome at https://github.com/Shubhojit2000/Kaggle-MCP-Agent/issues. For the most impactful contribution, the project would benefit from:

1. Upstream-fix the kernel_push slug bug in the community kaggle-mcp-server so the MCP tool itself supports pushing new versions of existing notebooks (then we can retire push.save_notebook_version).
2. GPU / TPU / internet flags on save_notebook_version (the kagglesdk request object supports them — we just need to expose them as CLI flags).
3. First-class script kernel support in the full workflow (currently untested end-to-end).

Run tests before submitting:

python -m pytest tests/ -v

---

License

MIT — see LICENSE.

---

Acknowledgements

• The community kaggle-mcp-server package, which provides the MCP server we drive.
• opencode for being a great agent host that natively supports stdio MCP servers.