kaggle-mcp

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. 저장소를 복제합니다.지엑스피1
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 파일이 다운로드됩니다.
   • 방법 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 클라이언트 또는 호환 도구를 사용하여 서버와 상호 작용할 수 있습니다.

Docker 컨테이너 실행

1. Kaggle API 자격 증명 설정

이 프로젝트에서는 Kaggle 데이터 세트에 액세스하기 위해 Kaggle API 자격 증명이 필요합니다.

• 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) :
  • 지정된 Kaggle 데이터 세트 참조에 대한 기본 탐색적 데이터 분석(EDA) 노트북을 생성하는 데 적합한 AI 모델(예: Gemini)에 적합한 프롬프트 메시지를 생성합니다.
  • 이 프롬프트에서는 데이터 로딩, 누락된 값 확인, 시각화 및 기본 통계를 다루는 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. 에이전트: "'user/heart-disease-dataset'에 대한 EDA 노트북 프롬프트를 생성하세요."
   • 서버는 generate_eda_notebook(dataset_ref='user/heart-disease-dataset') 실행합니다.
   • 서버는 구조화된 프롬프트 메시지를 반환합니다.
4. 에이전트: (프롬프트를 코드 생성 모델로 전송) -> EDA Python 코드를 수신합니다.