kaggle-mcp

Kaggle MCP (Model Context Protocol) Server

This repository contains an MCP (Model Context Protocol) server (server.py) built using the fastmcp library. It interacts with the Kaggle API to provide tools for searching and downloading datasets, and a prompt for generating EDA notebooks.

Project Structure

• server.py: The FastMCP server application. It defines resources, tools, and prompts for interacting with Kaggle.
• .env.example: An example file for environment variables (Kaggle API credentials). Rename to .env and fill in your details.
• requirements.txt: Lists the necessary Python packages.
• pyproject.toml & uv.lock: Project metadata and locked dependencies for uv package manager.
• datasets/: Default directory where downloaded Kaggle datasets will be stored.

Setup

1. Clone the repository:
   git clone <repository-url> cd <repository-directory>
2. Create a virtual environment (recommended):
   python -m venv venv source venv/bin/activate # On Windows use `venv\Scripts\activate` # Or use uv: uv venv
3. Install dependencies: Using pip:
   pip install -r requirements.txt
   Or using uv:
   uv sync
4. Set up Kaggle API credentials:
   • Method 1 (Recommended): Environment Variables
     • Create .env file
     • Open the .env file and add your Kaggle username and API key:
       KAGGLE_USERNAME=your_kaggle_username KAGGLE_KEY=your_kaggle_api_key
     • You can obtain your API key from your Kaggle account page (Account > API > Create New API Token). This will download a kaggle.json file containing your username and key.
   • Method 2: kaggle.json file
     • Download your kaggle.json file from your Kaggle account.
     • Place the kaggle.json file in the expected location (usually ~/.kaggle/kaggle.json on Linux/macOS or C:\Users\<Your User Name>\.kaggle\kaggle.json on Windows). The kaggle library will automatically detect this file if the environment variables are not set.

Running the Server

1. Ensure your virtual environment is active.
2. Run the MCP server:
   uv run kaggle-mcp
   The server will start and register its resources, tools, and prompts. You can interact with it using an MCP client or compatible tools.

Running the Docker Container

1. Set up Kaggle API credentials

This project requires Kaggle API credentials to access Kaggle datasets.

• Go to https://www.kaggle.com/settings and click "Create New API Token" to download your kaggle.json file.
• Open the kaggle.json file and copy your username and key into a new .env file in the project root:

2. Build the Docker image

3. Run the Docker container using your .env file

This will automatically load your Kaggle credentials as environment variables inside the container.

Server Features

The server exposes the following capabilities through the Model Context Protocol:

Tools

• search_kaggle_datasets(query: str):
  • Searches for datasets on Kaggle matching the provided query string.
  • Returns a JSON list of the top 10 matching datasets with details like reference, title, download count, and last updated date.
• download_kaggle_dataset(dataset_ref: str, download_path: str | None = None):
  • Downloads and unzips files for a specific Kaggle dataset.
  • dataset_ref: The dataset identifier in the format username/dataset-slug (e.g., kaggle/titanic).
  • download_path (Optional): Specifies where to download the dataset. If omitted, it defaults to ./datasets/<dataset_slug>/ relative to the server script's location.

Prompts

• generate_eda_notebook(dataset_ref: str):
  • Generates a prompt message suitable for an AI model (like Gemini) to create a basic Exploratory Data Analysis (EDA) notebook for the specified Kaggle dataset reference.
  • The prompt asks for Python code covering data loading, missing value checks, visualizations, and basic statistics.

Connecting to Claude Desktop

Go to Claude > Settings > Developer > Edit Config > claude_desktop_config.json to include the following:

Usage Example

An AI agent or MCP client could interact with this server like this:

1. Agent: "Search Kaggle for datasets about 'heart disease'"
   • Server executes search_kaggle_datasets(query='heart disease')
2. Agent: "Download the dataset 'user/heart-disease-dataset'"
   • Server executes download_kaggle_dataset(dataset_ref='user/heart-disease-dataset')
3. Agent: "Generate an EDA notebook prompt for 'user/heart-disease-dataset'"
   • Server executes generate_eda_notebook(dataset_ref='user/heart-disease-dataset')
   • Server returns a structured prompt message.
4. Agent: (Sends the prompt to a code-generating model) -> Receives EDA Python code.