🛒 Kroger MCP 서버 🛍️ -- Kroger 쇼핑을 위한 FastMCP

Claude와 같은 AI 비서가 Model Context Protocol( MCP )을 통해 크로거의 식료품 쇼핑 기능에 원활하게 접근할 수 있도록 지원하는 FastMCP 서버입니다. 이 서버를 통해 AI 비서는 매장 검색, 제품 검색, 장바구니 관리, 그리고 크로거-api 파이썬 라이브러리를 통한 크로거의 종합적인 식료품 데이터에 접근할 수 있습니다.

📺 데모

이 MCP 서버와 함께 Claude를 사용하여 매장을 검색하고, 제품을 찾고, 장바구니에 항목을 추가합니다.

Related MCP server: mcp-carrefour

🚀 빠른 시작

필수 조건

Kroger API 자격 증명이 필요합니다( Kroger Developer Portal 에서 무료로 제공). Kroger Developer Portal을 방문하여 다음 작업을 수행하세요.

1. 개발자 계정 만들기

2. 신청서를 등록하세요

3. CLIENT_ID , CLIENT_SECRET 가져오고 REDIRECT_URI 설정하세요.

사용자 인증이 필요한 도구를 처음 실행하면 웹 브라우저를 통해 앱을 승인하라는 메시지가 표시됩니다. 제3자가 아닌, 등록된 본인 앱 에 권한을 부여하는 것입니다.

설치

옵션 1: Claude Desktop과 함께 uvx 사용(권장)

PyPI에 게시하면 저장소를 복제하지 않고도 uvx를 사용하여 패키지를 직접 실행할 수 있습니다.

Claude Desktop의 구성 파일을 편집합니다.

macOS : ~/Library/Application Support/Claude/claude_desktop_config.json

리눅스 : ~/.config/Claude/claude_desktop_config.json

윈도우 : %APPDATA%/Claude/claude_desktop_config.json

지엑스피1

이 방법의 이점:

• 필요한 경우 PyPI에서 패키지를 자동으로 설치합니다.

• 서버를 실행하기 위한 격리된 환경을 만듭니다.

• 최신 버전으로 쉽게 업데이트할 수 있습니다.

• 로컬 저장소 복제본을 유지할 필요가 없습니다.

옵션 2: 로컬 복제본과 함께 uv 사용

먼저 로컬로 복제합니다.

git clone https://github.com/CupOfOwls/kroger-mcp

그런 다음 Claude Desktop의 구성 파일을 편집합니다.

{
  "mcpServers": {
    "kroger": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/cloned/kroger-mcp",
        "run",
        "kroger-mcp"
      ],
      "env": {
        "KROGER_CLIENT_ID": "your_client_id",
        "KROGER_CLIENT_SECRET": "your_client_secret", 
        "KROGER_REDIRECT_URI": "http://localhost:8000/callback",
        "KROGER_USER_ZIP_CODE": "10001"
      }
    }
  }
}

옵션 3: PyPI에서 설치

# Install with uv (recommended)
uv pip install kroger-mcp

# Or install with pip
pip install kroger-mcp

옵션 4: 소스에서 설치

# Clone the repository
git clone https://github.com/CupOfOwls/kroger-mcp
cd kroger-mcp

# Install with uv (recommended)
uv sync

# Or install with pip
pip install -e .

구성

프로젝트 루트에 .env 파일을 만들거나 JSON 구성을 통해 env 값을 전달하세요.

# Required: Your Kroger API credentials
KROGER_CLIENT_ID=your_client_id_here
KROGER_CLIENT_SECRET=your_client_secret_here
KROGER_REDIRECT_URI=http://localhost:8000/callback

# Optional: Default zip code for location searches
KROGER_USER_ZIP_CODE=90274

서버 실행

# With uv (recommended)
uv run kroger-mcp

# With uvx (directly from PyPI without installation)
uvx kroger-mcp

# Or with Python directly
python server.py

# With FastMCP CLI for development
fastmcp dev server.py --with-editable .

🛠️ 특징

💬 내장 MCP 프롬프트

• 쇼핑 경로 : 식료품 목록에 대한 매장 내 최적 경로 찾기

• 약국 확인 : 원하는 위치의 약국이 열려 있는지 확인하세요

• 매장 선택 : 사용자가 선호하는 Kroger 매장을 설정하는 데 도움이 됩니다.

• 레시피 쇼핑 : 레시피를 찾고 재료를 장바구니에 담으세요

📚 사용 가능한 도구

위치 도구

제품 도구

카트 도구

정보 도구

프로필 도구

유틸리티 도구

🧰 로컬 전용 카트 추적

Kroger API는 장바구니 보기 기능을 제공하지 않으므로 이 서버는 로컬 추적을 유지합니다.

로컬 카트 보관

• 파일 : kroger_cart.json

• 내용 : 타임스탬프가 포함된 현재 장바구니 항목

• 자동 : 자동으로 생성 및 업데이트됨

주문 내역

• 파일 : kroger_order_history.json

• 내용 : 배치 타임스탬프가 포함된 과거 주문

• 사용법 : mark_order_placed 사용하여 완료된 장바구니를 기록으로 이동합니다.

🚧 Kroger 공개 API 제한 사항

• 보기 전용 : remove_from_cart 및 clear_current_cart 도구는 실제 Kroger 카트가 아닌 로컬 추적에만 영향을 미칩니다.

• 로컬 동기화 : 사용자가 Kroger 앱/웹사이트에서 장바구니에서 항목을 이미 제거한 경우에만 이 도구를 사용하세요.

• 일방통행 : 공개 API를 통해 상품을 크로거 장바구니에 추가할 수는 있지만 삭제할 수는 없습니다. 파트너 API를 사용하면 이러한 기능이 가능하지만, 이를 위해서는 크로거와 계약을 체결해야 합니다.

참고: 속도 제한은 작업 단위가 아닌 엔드포인트 단위로 적용됩니다. 필요에 따라 동일한 엔드포인트를 사용하여 여러 작업에 호출을 분산할 수 있습니다.

🏫 기본 워크플로

1. 선호하는 위치를 설정하세요 :

   User: "Find Kroger stores near 90274"
   Assistant: [Uses search_locations tool]
   User: "Set the first one as my preferred location"
   Assistant: [Uses set_preferred_location tool]

2. 제품 검색 및 추가 :

   User: "Add milk to my cart"
   Assistant: [Uses search_products, then add_items_to_cart]
   
   User: "Add bread, eggs, and cheese to my cart"
   Assistant: [Uses search_products for each, then bulk_add_to_cart]

3. 장바구니 및 주문 관리 :

   User: "What's in my cart?"
   Assistant: [Uses view_current_cart tool to see local memory]
   
   User: "I placed the order on the Kroger website"
   Assistant: [Uses mark_order_placed tool, moving current cart to the order history]

🤝 기여하기

기여를 환영합니다! 풀 리퀘스트를 제출해 주세요. 주요 변경 사항의 경우, 먼저 이슈를 열어 변경 사항을 논의해 주세요.

📄 라이센스

이 프로젝트는 MIT 라이선스에 따라 라이선스가 부여되었습니다. 자세한 내용은 라이선스 파일을 참조하세요.

⚠️ 면책 조항

이 서버는 Kroger Public API를 위한 비공식 MCP 서버입니다. Kroger와 제휴, 보증 또는 후원을 받지 않습니다.

Kroger API에 대한 질문이 있으면 Kroger 개발자 포털을 방문하거나 kroger-api 패키지 문서를 읽어보세요.