Kaggle MCP (Model Context Protocol) Server

1[![smithery badge](https://smithery.ai/badge/@arrismo/kaggle-mcp)](https://smithery.ai/server/@arrismo/kaggle-mcp)
2<a href="https://glama.ai/mcp/servers/arwswog1el"><img width="380" height="200" src="https://glama.ai/mcp/servers/arwswog1el/badge" alt="Kaggle MCP Server" /></a>
3 
4# Kaggle MCP (Model Context Protocol) Server
5This 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.
6 
7## Project Structure
8 
9-   `server.py`: The FastMCP server application. It defines resources, tools, and prompts for interacting with Kaggle.
10-   `.env.example`: An example file for environment variables (Kaggle API credentials). Rename to `.env` and fill in your details.
11-   `requirements.txt`: Lists the necessary Python packages.
12-   `pyproject.toml` & `uv.lock`: Project metadata and locked dependencies for `uv` package manager.
13-   `datasets/`: Default directory where downloaded Kaggle datasets will be stored.
14 
15## Setup
16 
171.  **Clone the repository:**
18    ```bash
19    git clone <repository-url>
20    cd <repository-directory>
21    ```
22 
232.  **Create a virtual environment (recommended):**
24    ```bash
25    python -m venv venv
26    source venv/bin/activate  # On Windows use `venv\Scripts\activate`
27    # Or use uv: uv venv
28    ```
29 
303.  **Install dependencies:**
31    Using pip:
32    ```bash
33    pip install -r requirements.txt
34    ```
35    Or using uv:
36    ```bash
37    uv sync
38    ```
39 
404.  **Set up Kaggle API credentials:**
41    -   **Method 1 (Recommended): Environment Variables**
42        -   Create `.env` file
43        -   Open the `.env` file and add your Kaggle username and API key:
44            ```dotenv
45            KAGGLE_USERNAME=your_kaggle_username
46            KAGGLE_KEY=your_kaggle_api_key
47            ```
48        -   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.
49    -   **Method 2: `kaggle.json` file**
50        -   Download your `kaggle.json` file from your Kaggle account.
51        -   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.
52 
53## Running the Server
54 
551.  **Ensure your virtual environment is active.**
562.  **Run the MCP server:**
57    ```bash
58    uv run kaggle-mcp
59    ```
60    The server will start and register its resources, tools, and prompts. You can interact with it using an MCP client or compatible tools.
61 
62## Running the Docker Container
63 
64### 1. Set up Kaggle API credentials
65 
66This project requires Kaggle API credentials to access Kaggle datasets.
67 
68- Go to https://www.kaggle.com/settings and click "Create New API Token" to download your `kaggle.json` file.
69- Open the `kaggle.json` file and copy your username and key into a new `.env` file in the project root:
70 
71```
72KAGGLE_USERNAME=your_username
73KAGGLE_KEY=your_key
74```
75 
76### 2. Build the Docker image
77 
78```sh
79docker build -t kaggle-mcp-test .
80```
81 
82### 3. Run the Docker container using your .env file
83 
84```sh
85docker run --rm -it --env-file .env kaggle-mcp-test
86```
87 
88This will automatically load your Kaggle credentials as environment variables inside the container.
89 
90---
91 
92 
93## Server Features
94 
95The server exposes the following capabilities through the Model Context Protocol:
96### Tools
97 
98*   **`search_kaggle_datasets(query: str)`**:
99    *   Searches for datasets on Kaggle matching the provided query string.
100    *   Returns a JSON list of the top 10 matching datasets with details like reference, title, download count, and last updated date.
101*   **`download_kaggle_dataset(dataset_ref: str, download_path: str | None = None)`**:
102    *   Downloads and unzips files for a specific Kaggle dataset.
103    *   `dataset_ref`: The dataset identifier in the format `username/dataset-slug` (e.g., `kaggle/titanic`).
104    *   `download_path` (Optional): Specifies where to download the dataset. If omitted, it defaults to `./datasets/<dataset_slug>/` relative to the server script's location.
105 
106### Prompts
107 
108*   **`generate_eda_notebook(dataset_ref: str)`**:
109    *   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.
110    *   The prompt asks for Python code covering data loading, missing value checks, visualizations, and basic statistics.
111 
112## Connecting to Claude Desktop 
113Go to Claude > Settings > Developer > Edit Config > claude_desktop_config.json to include the following:
114 
115```
116{
117  "mcpServers": {
118    "kaggle-mcp": {
119      "command": "kaggle-mcp",
120      "cwd": "<path-to-their-cloned-repo>/kaggle-mcp"
121    }
122  }
123}
124```
125 
126## Usage Example
127 
128An AI agent or MCP client could interact with this server like this:
129 
1301.  **Agent:** "Search Kaggle for datasets about 'heart disease'"
131    *   *Server executes `search_kaggle_datasets(query='heart disease')`*
1322.  **Agent:** "Download the dataset 'user/heart-disease-dataset'"
133    *   *Server executes `download_kaggle_dataset(dataset_ref='user/heart-disease-dataset')`*
1343.  **Agent:** "Generate an EDA notebook prompt for 'user/heart-disease-dataset'"
135    *   *Server executes `generate_eda_notebook(dataset_ref='user/heart-disease-dataset')`*
136    *   *Server returns a structured prompt message.*
1374.  **Agent:** (Sends the prompt to a code-generating model) -> Receives EDA Python code.
138