# Kaggle MCP Server

A full-featured [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server for the Kaggle API — **96 tools** across competitions, datasets, kernels, models, benchmarks, discussions, and workflow utilities.

## Installation

```bash
pip install kaggle-mcp-server
```

### Prerequisites

1. **Kaggle API credentials** — place your `kaggle.json` at `~/.kaggle/kaggle.json`:

```json
{"username":"YOUR_USERNAME","key":"YOUR_API_KEY"}
```

Get your API key from [kaggle.com/settings](https://www.kaggle.com/settings) → "Create New Token".

2. **Python 3.12+**

## Usage

### With Cursor IDE

Add to `.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "kaggle": {
      "command": "kaggle-mcp-server"
    }
  }
}
```

### With Claude Desktop

Add to your Claude Desktop config:

```json
{
  "mcpServers": {
    "kaggle": {
      "command": "kaggle-mcp-server"
    }
  }
}
```

### Standalone

```bash
kaggle-mcp-server
```

## Tools (96 total)

### Competitions (16 tools)
| Tool | Description |
|------|-------------|
| `competitions_list` | Search and list competitions |
| `competition_get` | Get detailed competition info |
| `competition_files` | List competition data files |
| `competition_tree_files` | Hierarchical tree view of competition data |
| `competition_download` | Download competition data (returns URL) |
| `competition_download_single_file` | Download a single competition file locally |
| `competition_submit` | Submit predictions via blob token |
| `submit_local_file` | Submit a local prediction file |
| `submit_code_competition` | Submit to code competitions |
| `competition_submissions` | View submission history |
| `competition_get_submission` | Get single submission details |
| `submission_score` | Get/poll submission score |
| `competition_leaderboard` | View top 20 leaderboard |
| `competition_leaderboard_download` | Download full leaderboard |
| `leaderboard_position` | Find a team/user's rank |
| `competition_data_summary` | Get data files summary |

### Competition Workflow (5 tools)
| Tool | Description |
|------|-------------|
| `setup_comp` | Download and extract competition data locally |
| `competition_full_setup` | One-shot setup: info + download + preview |
| `upcoming_deadlines` | Show competitions with closest deadlines |
| `my_competitions` | List competitions you've entered |
| `competition_top_kernels` | Top public notebooks for a competition |

### Datasets (20 tools)
| Tool | Description |
|------|-------------|
| `datasets_list` | Search and list datasets |
| `dataset_get` | Get full dataset info |
| `dataset_files` | List files in a dataset |
| `dataset_tree_files` | Hierarchical tree view of dataset files |
| `dataset_files_summary` | Get file count and total size |
| `dataset_download` | Download dataset (returns URL) |
| `dataset_download_file` | Download a single dataset file |
| `download_dataset_local` | Download and extract dataset locally |
| `dataset_metadata` | Get dataset metadata |
| `dataset_update_metadata` | Update title/description/license |
| `dataset_create` | Create dataset via blob tokens |
| `create_dataset_from_files` | Create dataset from local directory |
| `dataset_create_version` | Create new version via tokens |
| `push_dataset_version` | Push new version from local directory |
| `dataset_delete` | Delete a dataset |
| `dataset_status` | Check dataset processing status |
| `file_upload` | Upload file and get blob token |
| `my_datasets` | List your datasets |
| `datasets_by_user` | List datasets by a specific user |
| `check_dataset_exists` | Check if a dataset exists |

### Kernels / Notebooks (15 tools)
| Tool | Description |
|------|-------------|
| `kernels_list` | Search and list notebooks |
| `kernel_pull` | Get notebook source code |
| `kernel_push` | Push/save a notebook |
| `push_notebook_file` | Push local .ipynb to Kaggle |
| `kernel_output` | Download kernel output (URL) |
| `kernel_download_output_zip` | Download kernel output locally |
| `kernel_status` | Check kernel execution status |
| `kernel_files` | List kernel files |
| `kernel_delete` | Delete a kernel |
| `kernel_initialize` | Initialize kernel template locally |
| `kernel_session_create` | Create interactive session |
| `kernel_session_status` | Get session status |
| `kernel_session_output` | List session output files |
| `kernel_session_cancel` | Cancel running session |
| `generate_notebook_metadata` | Generate kernel-metadata.json |

### Models (16 tools)
| Tool | Description |
|------|-------------|
| `models_list` | Search and list models |
| `model_get` | Get model details |
| `model_create` | Create a new model |
| `model_update` | Update model info |
| `model_delete` | Delete a model |
| `model_metrics` | Get model performance metrics |
| `model_instances_list` | List model instances |
| `model_instance_get` | Get instance details |
| `model_instance_create` | Create a new instance |
| `model_instance_delete` | Delete an instance |
| `model_instance_files` | List instance files |
| `model_instance_versions` | List instance versions |
| `model_instance_version_create` | Create new version |
| `model_instance_version_download` | Download version files |
| `model_instance_version_files` | List version files |
| `model_instance_version_delete` | Delete a version |

### Discussions (10 tools)
| Tool | Description |
|------|-------------|
| `discussions_search` | Search discussions |
| `discussions_list` | List discussions for competition/dataset |
| `discussion_detail` | Get discussion content |
| `discussion_comments` | Get discussion comments |
| `discussion_comments_search` | Search across all comments |
| `discussions_by_source` | Browse by source type |
| `discussions_solutions` | Browse competition solutions |
| `discussions_writeups` | Browse write-ups by type |
| `discussions_trending` | Browse trending discussions |
| `discussions_my` | List your discussions |

### Benchmarks (1 tool)
| Tool | Description |
|------|-------------|
| `benchmark_leaderboard` | Get benchmark leaderboard |

### Data Preview & Analysis (4 tools)
| Tool | Description |
|------|-------------|
| `preview_csv` | Preview first N rows of a CSV |
| `preview_data_file` | Preview any text data file |
| `csv_column_analysis` | Analyze column types and stats |
| `compare_csvs` | Diff two CSV files |

### Workflow Utilities (9 tools)
| Tool | Description |
|------|-------------|
| `generate_starter_notebook` | Auto-generate competition starter notebook |
| `search_everything` | Unified search across competitions, datasets, notebooks |
| `list_local_files` | List local files with sizes |
| `track_operation` | Monitor long-running Kaggle operations |
| `download_pip_library` | Download pip wheels for offline use |
| `download_pip_requirements` | Download requirements.txt wheels |
| `create_library_dataset` | Upload pip library as Kaggle dataset |
| `create_requirements_dataset` | Upload requirements as Kaggle dataset |
| `get_local_library_version` | Check local wheel version |

## License

MIT