Kaggle MCP Server
# <img src="https://www.kaggle.com/static/images/site-logo.svg" alt="Kaggle Logo" width="80" height="24"> Kaggle MCP Server
[](https://github.com/Dishant27/kaggle-MCP/actions/workflows/ci.yml)
[](LICENSE)
A Model Context Protocol (MCP) server for interacting with Kaggle competitions through Claude or other compatible AI assistants.
## ⚠️ Status and known limitations (read this first)
- **Competitions only on `main`.** Datasets, notebooks and user tools live in the unmerged [`feature/extended-functionality`](https://github.com/Dishant27/kaggle-MCP/tree/feature/extended-functionality) branch.
- **Wraps the Kaggle CLI.** Every tool shells out to `kaggle`, so the CLI must be installed (`pip install kaggle`) and on your `PATH`. Output formats follow whatever CLI version you have installed.
- **Your own Kaggle account and limits apply.** Downloads and submissions only work for competitions whose rules you've accepted on kaggle.com, and Kaggle's daily submission limits still apply.
- **Credentials are never logged.** They come from `~/.kaggle/kaggle.json` or the `KAGGLE_USERNAME` / `KAGGLE_KEY` env vars and are passed straight to the CLI.
- **Tests are light.** CI type-checks, builds and runs a small credential-handling test on Node 20 and 22; the tools themselves aren't tested against the live Kaggle API.
## 📖 Learn More
Want to understand the full potential of this server? Check out the detailed article:
[AI-Powered Data Science Revolution: How Kaggle MCP Server Transforms AI Capabilities](https://www.linkedin.com/pulse/ai-powered-data-science-revolution-how-kaggle-mcp-server-kumar-zn7sc/)
## Prerequisites
- Node.js 18 or higher
- TypeScript
- Kaggle CLI installed (`pip install kaggle`)
- Kaggle API credentials configured
## Authentication Setup
There are two ways to authenticate with the Kaggle API:
### Option 1: Using a kaggle.json file (Standard approach)
1. Install the Kaggle CLI:
```bash
pip install kaggle
```
2. Go to https://www.kaggle.com/account and click "Create New API Token"
3. This will download a `kaggle.json` file with your credentials
4. Create a `.kaggle` directory in your home folder (if it doesn't exist)
```bash
# On Linux/Mac
mkdir -p ~/.kaggle
# On Windows (PowerShell)
New-Item -ItemType Directory -Force -Path "$HOME\.kaggle"
```
5. Move the downloaded `kaggle.json` file to the `.kaggle` directory:
```bash
# On Linux/Mac
mv ~/Downloads/kaggle.json ~/.kaggle/
chmod 600 ~/.kaggle/kaggle.json # Set permissions
# On Windows (PowerShell)
Move-Item -Path "$HOME\Downloads\kaggle.json" -Destination "$HOME\.kaggle\kaggle.json"
```
### Option 2: Using Claude for Desktop Configuration (Simpler)
You can directly add your Kaggle credentials to your `claude_desktop_config.json` file:
```json
{
"mcpServers": {
"kaggle": {
"command": "node",
"args": ["/path/to/build/index.js"],
"env": {
"KAGGLE_USERNAME": "your-kaggle-username",
"KAGGLE_KEY": "your-kaggle-api-key"
}
}
}
}
```
Replace `your-kaggle-username` and `your-kaggle-api-key` with your actual Kaggle credentials.
## Installation
1. Clone this repository
2. Install dependencies:
```bash
npm install
```
3. Build the project:
```bash
npm run build
```
## Usage
### Running the server
```bash
npm start
```
Or directly:
```bash
node build/index.js
```
### Connecting with Claude for Desktop
Add the following configuration to your `claude_desktop_config.json` file (use the absolute path to your clone):
```json
{
"mcpServers": {
"kaggle": {
"command": "node",
"args": ["/absolute/path/to/kaggle-MCP/build/index.js"]
}
}
}
```
Add the `env` block from Option 2 above if you aren't using `kaggle.json`.
## Example Queries
Once connected to Claude, you can ask questions like:
- "Show me the active Kaggle competitions"
- "Search for image classification competitions"
- "Download the files for the Titanic competition"
- "Submit my predictions.csv file to the housing-prices competition with the message 'Random forest model'"
- "Show me my submissions for the digit-recognizer competition"
## Troubleshooting
### Authentication Issues
If you encounter authentication errors:
1. Verify your credentials are correctly set:
- If using `kaggle.json`, check it's in the correct location:
- Linux/Mac: `~/.kaggle/kaggle.json`
- Windows: `C:\Users\<USERNAME>\.kaggle\kaggle.json`
- If using environment variables, check the `env` section in your `claude_desktop_config.json`
2. For `kaggle.json`, check if the file has the correct permissions:
- On Linux/Mac, run: `chmod 600 ~/.kaggle/kaggle.json`
3. Make sure your API token is still valid. If needed, generate a new one from your Kaggle account page.
### Installation Issues
If the Kaggle CLI is not found:
1. Make sure you have installed it with: `pip install kaggle`
2. Verify that the Kaggle command is in your PATH by running: `kaggle --version`
## Current Capabilities
The server currently provides the following operations for Kaggle competitions:
### 🔍 List Competitions
- List all active Kaggle competitions
- Search competitions by keyword
- Support for pagination to browse through results
- Display competition details including name, category, deadline, and prize
### 📥 Download Competition Files
- Download files for any competition
- Specify custom download path
- Force re-download of existing files
- Works with all public competition datasets
### 📤 Submit to Competitions
- Submit prediction files to competitions
- Add custom submission messages
- Get immediate feedback on submission status
- Requires prior acceptance of competition rules on Kaggle website
### 📋 List Submissions
- View submission history for a specific competition
- See submission status and scores
- Track multiple submissions over time
## Extended Features (separate branch)
More tools live in the [`feature/extended-functionality`](https://github.com/Dishant27/kaggle-MCP/tree/feature/extended-functionality) branch, which hasn't been merged into `main` yet. It covers:
- **Dataset Operations**: Browse, search, download, and analyze datasets from Kaggle
- **Notebook Integration**: Work with Kaggle notebooks directly from your AI assistant
- **User Management**: Check profile information and competition standings
- **Competition Analysis**: Get detailed competition metrics and leaderboard insights
Check out that branch if you need more than competitions.
## License
[MIT](LICENSE)
TDQS
Scored across 4 tools
The four tools target distinct resources and actions: listing competitions, downloading a competition, submitting to a competition, and listing submissions. Without descriptions, some scope details are ambiguous, such as exactly what download-competition returns or whether list-submissions is competition-scoped or user-scoped.
All names use kebab-case and generally follow a verb-object pattern: list-competitions, download-competition, list-submissions. submit-to-competition is slightly less consistent because it inserts a preposition, but the overall convention is still predictable.
Four tools is a compact but reasonable surface for a competition-focused Kaggle server. It may be slightly thin, but each tool has a clear role in the basic competition workflow.
The surface covers listing competitions, downloading competition data, submitting, and listing submissions, but notable competition operations are missing, such as getting competition details, viewing leaderboards, or listing competition files. These gaps would limit an agent's ability to fully navigate Kaggle competitions.