Kaggle MCP (模型上下文协议) 服务器

此仓库包含一个使用 fastmcp 库构建的MCP（Model Context Protocol，模型上下文协议）服务器 (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  # 在 Windows 上使用 `venv\Scripts\activate`
   # 或者使用 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 账户页面获取 API 密钥（账户 > API > 创建新的 API Token）。这将下载一个包含您的用户名和密钥的 kaggle.json 文件。
   • 方法 2：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 客户端或兼容工具与其交互。

服务器功能

该服务器通过模型上下文协议提供了以下功能：

工具

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

提示

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

连接到Claude桌面版

转到Claude > 设置 > 开发者 > 编辑配置 > claude_desktop_config.json，添加以下内容：

{
  "mcpServers": {
    "kaggle-mcp": {
      "command": "kaggle-mcp",
      "cwd": "<path-to-their-cloned-repo>/kaggle-mcp"
    }
  }
}

使用示例

一个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. 代理: "为'user/heart-disease-dataset'生成一个EDA笔记本提示"
   • 服务器执行 generate_eda_notebook(dataset_ref='user/heart-disease-dataset')
   • 服务器返回结构化的提示消息。
4. 代理: (将提示发送给代码生成模型) -> 接收EDA Python代码。