kaggle-mcp

Kaggle MCP（模型上下文协议）服务器

此代码库包含一个使用fastmcp库构建的 MCP（模型上下文协议）服务器 ( server.py )。它与 Kaggle API 交互，提供用于搜索和下载数据集的工具，以及生成 EDA 笔记本的提示。

项目结构

• server.py ：FastMCP 服务器应用程序。它定义了与 Kaggle 交互的资源、工具和提示。
• .env.example ：环境变量（Kaggle API 凭证）的示例文件。重命名为.env并填写您的详细信息。
• requirements.txt ：列出必要的 Python 包。
• pyproject.toml & uv.lock ： uv包管理器的项目元数据和锁定依赖项。
• datasets/ ：下载的 Kaggle 数据集的默认存储目录。

设置

1. 克隆存储库：
   git clone <repository-url> cd <repository-directory>
2. 创建虚拟环境（推荐）：
   python -m venv venv source venv/bin/activate # On Windows use `venv\Scripts\activate` # Or use uv: uv venv
3. **安装依赖项：**使用 pip：
   pip install -r requirements.txt
   或者使用 uv：
   uv sync
4. 设置 Kaggle API 凭证：
   • 方法 1（推荐）：环境变量
     • 创建.env文件
     • 打开.env文件并添加您的 Kaggle 用户名和 API 密钥：
       KAGGLE_USERNAME=your_kaggle_username KAGGLE_KEY=your_kaggle_api_key
     • 您可以从 Kaggle 帐户页面（ Account > API > Create New API Token ）获取 API 密钥。这将下载一个包含您的用户名和密钥的kaggle.json文件。
   • 方法二： kaggle.json文件
     • 从您的 Kaggle 帐户下载您的kaggle.json文件。
     • 将kaggle.json文件放置在预期位置（Linux/macOS 上通常为~/.kaggle/kaggle.json ，Windows 上通常C:\Users\<Your User Name>\.kaggle\kaggle.json ）。如果未设置环境变量， kaggle库将自动检测此文件。

运行服务器

1. 确保您的虚拟环境处于活动状态。
2. 运行 MCP 服务器：
   uv run kaggle-mcp
   服务器将启动并注册其资源、工具和提示。您可以使用 MCP 客户端或兼容工具与其交互。

运行 Docker 容器

1. 设置 Kaggle API 凭证

该项目需要 Kaggle API 凭证来访问 Kaggle 数据集。

• 转到https://www.kaggle.com/settings并单击“创建新 API 令牌”以下载您的kaggle.json文件。
• 打开kaggle.json文件并将您的用户名和密钥复制到项目根目录中的新.env文件中：

2.构建Docker镜像

3. 使用 .env 文件运行 Docker 容器

这将自动将您的 Kaggle 凭据作为容器内的环境变量加载。

服务器功能

服务器通过模型上下文协议公开以下功能：

工具

• search_kaggle_datasets(query: str) ：
  • 在 Kaggle 上搜索与提供的查询字符串匹配的数据集。
  • 返回前 10 个匹配数据集的 JSON 列表，其中包含参考、标题、下载次数和上次更新日期等详细信息。
• download_kaggle_dataset(dataset_ref: str, download_path: str | None = None) ：
  • 下载并解压特定 Kaggle 数据集的文件。
  • dataset_ref ：格式为username/dataset-slug数据集标识符（例如， kaggle/titanic ）。
  • download_path （可选）：指定数据集的下载位置。如果省略，则默认为相对于服务器脚本位置的./datasets/<dataset_slug>/ 。

提示

• generate_eda_notebook(dataset_ref: str) ：
  • 生成适合 AI 模型（如 Gemini）的提示消息，为指定的 Kaggle 数据集参考创建基本的探索性数据分析 (EDA) 笔记本。
  • 提示要求提供涵盖数据加载、缺失值检查、可视化和基本统计的 Python 代码。

连接到 Claude Desktop

转到 Claude > 设置 > 开发人员 > 编辑配置 > claude_desktop_config.json 以包含以下内容：

使用示例

AI 代理或 MCP 客户端可以像这样与该服务器交互：

1. 代理： “在 Kaggle 上搜索关于‘心脏病’的数据集”
   • 服务器执行search_kaggle_datasets(query='heart disease')
2. 代理： “下载数据集‘user/heart-disease-dataset’”
   • 服务器执行download_kaggle_dataset(dataset_ref='user/heart-disease-dataset')
3. 代理： “为‘用户/心脏病数据集’生成 EDA 笔记本提示”
   • 服务器执行generate_eda_notebook(dataset_ref='user/heart-disease-dataset')
   • 服务器返回结构化的提示信息。
4. **代理：（**将提示发送到代码生成模型）->接收 EDA Python 代码。