# Kaggle MCP Server (Cloud & Koyeb Ready) 🚀

A full-featured Model Context Protocol (MCP) server for Kaggle, adapted to run on **Koyeb** (and any container or serverless cloud) over **Server-Sent Events (SSE)**.

Supports remote execution on **Kaggle Jupyter Servers (GPU/TPU)**, Kaggle Competitions, Datasets, Kernels, and Discussions.

---

## ⚡ Deployment on Koyeb

You can deploy this repository to Koyeb **without Docker** using Koyeb's native Buildpack, or with Docker.

### Option 1: Without Docker (Koyeb Buildpack - Recommended)

1. Fork or push this repository to your GitHub account: `https://github.com/Ragu-123/kaggle-mcp`
2. Log in to [Koyeb Console](https://app.koyeb.com).
3. Click **Create Service** → Select **GitHub**.
4. Select repository `Ragu-123/kaggle-mcp` and branch `main`.
5. Under **Builder**, select **Buildpack** (Koyeb will automatically detect `requirements.txt` and `Procfile`).
6. Under **Environment Variables & Secrets**, add:
   - `KAGGLE_USERNAME`: Your Kaggle username
   - `KAGGLE_KEY`: Your Kaggle API key (from https://www.kaggle.com/settings -> API)
   - `MCP_TRANSPORT`: `sse` (default)
   - `PORT`: `8000` (default)
7. Under **Ports**, expose port `8000` as `HTTP` with path `/`.
8. Click **Deploy**.

Koyeb will assign your service a public URL, for example: `https://<service-name>-<org>.koyeb.app`.

### Option 2: Docker Deployment

If you prefer building from `Dockerfile`:
- Under **Builder**, select **Dockerfile**.
- Add the same environment secrets (`KAGGLE_USERNAME`, `KAGGLE_KEY`).
- Click **Deploy**.

---

## 🔌 Connecting Remote AI Agents

Once deployed, connect your AI agents (Claude, ChatGPT, LibreChat, Cursor, Antigravity, OpenCode, etc.) using the SSE URL:

```text
https://<your-koyeb-subdomain>.koyeb.app/sse
```

### Health Check
You can test the server anytime in your browser or with curl:
```bash
curl https://<your-koyeb-subdomain>.koyeb.app/health
```
Response:
```json
{
  "status": "healthy",
  "service": "kaggle-agent-mcp",
  "transport": "sse",
  "sse_endpoint": "/sse",
  "messages_endpoint": "/messages/"
}
```

---

## 🛠️ Key Capabilities & Flexible Paths

### 1. Kaggle Remote Kernel Execution (GPU/TPU)
- `kaggle_remote_kernel_set_url(url)`: Connect to a Kaggle Jupyter notebook server.
- `kaggle_remote_kernel_execute(code, file_path, timeout)`: Execute code or scripts directly on the remote Kaggle GPU/TPU kernel.
- `kaggle_remote_kernel_job_status(job_id)`: Check execution status (`running`, `completed`, `failed`).
- `kaggle_remote_kernel_job_logs(job_id)`: Retrieve stdout and stderr logs.
- `kaggle_remote_kernel_wait_for_job(job_id)`: Wait until execution completes.
- `kaggle_remote_kernel_job_cancel(job_id)`: Interrupt and abort kernel execution.

### 2. Flexible Download Directories
Every tool that downloads files supports an optional `path` parameter so agents can specify their own local or workspace directories:
- `competition_download(competition, file_name, path)`: Download competition data directly into `path`.
- `competition_leaderboard_download(competition, path)`: Download leaderboard CSV into `path`.
- `dataset_download(owner, dataset_slug, file_name, path, unzip)`: Download and unpack datasets into `path`.
- `dataset_download_file(owner, dataset_slug, file_name, path)`: Download single dataset file into `path`.
- `kernel_pull(kernel, path, competition_slug)`: Pull notebook and metadata directly into `path`.
- `kernel_output(kernel, path)`: Pull kernel execution outputs into `path`.

---

## 🔒 Security Best Practice

Do NOT commit your Kaggle API key or username to GitHub. Always configure them as **Koyeb Secrets / Environment Variables** in the Koyeb web dashboard.