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

Name: Kroger MCP Server
Author: CupOfOwls

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

📺 데모

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

크로거 MCP 데모

Related MCP server: Agora MCP

🚀 빠른 시작

필수 조건

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

개발자 계정 만들기
신청서를 등록하세요
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 매장을 설정하는 데 도움이 됩니다.
레시피 쇼핑 : 레시피를 찾고 재료를 장바구니에 담으세요

📚 사용 가능한 도구

위치 도구

도구	설명	승인 필요
`search_locations`	우편번호 근처의 Kroger 매장 찾기	아니요
`get_location_details`	특정 매장에 대한 자세한 정보를 얻으세요	아니요
`set_preferred_location`	향후 운영을 위한 선호하는 매장 설정	아니요
`get_preferred_location`	현재 설정된 선호 매장을 가져옵니다	아니요
`check_location_exists`	위치 ID가 유효한지 확인하세요	아니요

제품 도구

도구	설명	승인 필요
`search_products`	이름, 브랜드 또는 기타 기준으로 제품을 검색하세요	아니요
`get_product_details`	가격을 포함한 자세한 제품 정보를 얻으세요	아니요
`search_products_by_id`	특정 제품 ID로 제품 찾기	아니요
`get_product_images`	특정 관점(앞면, 뒷면 등)에서 제품 이미지를 가져옵니다.	아니요

카트 도구

도구	설명	승인 필요
`add_items_to_cart`	장바구니에 단일 품목 추가	예
`bulk_add_to_cart`	한 번의 작업으로 여러 항목을 장바구니에 추가하세요	예
`view_current_cart`	현재 로컬 카트 추적에 있는 항목 보기	아니요
`remove_from_cart`	로컬 카트 추적에서 항목 제거	아니요
`clear_current_cart`	로컬 카트 추적에서 모든 항목을 지웁니다.	아니요
`mark_order_placed`	현재 장바구니를 주문 내역으로 이동	아니요
`view_order_history`	주문 내역 보기	아니요

정보 도구

도구	설명	승인 필요
`list_chains`	Kroger 소유의 모든 체인점을 만나보세요	아니요
`get_chain_details`	특정 체인에 대한 세부 정보를 얻으세요	아니요
`check_chain_exists`	체인이 존재하는지 확인하세요	아니요
`list_departments`	모든 매장 부서를 가져오세요	아니요
`get_department_details`	특정 부서에 대한 세부 정보를 얻으세요	아니요
`check_department_exists`	부서가 존재하는지 확인하세요	아니요

프로필 도구

도구	설명	승인 필요
`get_user_profile`	인증된 사용자의 프로필 정보를 가져옵니다.	예
`test_authentication`	인증 토큰이 유효한지 테스트	예
`get_authentication_info`	자세한 인증 상태 가져오기	예
`force_reauthenticate`	토큰을 지우고 강제로 재인증합니다.	아니요

유틸리티 도구

도구	설명	승인 필요
`get_current_datetime`	현재 시스템 날짜 및 시간 가져오기	아니요

🧰 로컬 전용 카트 추적

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

로컬 카트 보관

파일 : kroger_cart.json
내용 : 타임스탬프가 포함된 현재 장바구니 항목
자동 : 자동으로 생성 및 업데이트됨

주문 내역

파일 : kroger_order_history.json
내용 : 배치 타임스탬프가 포함된 과거 주문
사용법 : mark_order_placed 사용하여 완료된 장바구니를 기록으로 이동합니다.

🚧 Kroger 공개 API 제한 사항

보기 전용 : remove_from_cart 및 clear_current_cart 도구는 실제 Kroger 카트가 아닌 로컬 추적에만 영향을 미칩니다.
로컬 동기화 : 사용자가 Kroger 앱/웹사이트에서 장바구니에서 항목을 이미 제거한 경우에만 이 도구를 사용하세요.
일방통행 : 공개 API를 통해 상품을 크로거 장바구니에 추가할 수는 있지만 삭제할 수는 없습니다. 파트너 API를 사용하면 이러한 기능이 가능하지만, 이를 위해서는 크로거와 계약을 체결해야 합니다.

API	버전	요금 제한	노트
권한 부여	1.0.13	특정 제한 없음	토큰 관리
제품	1.2.4	10,000통화/일	검색 및 제품 세부 정보
위치	1.2.2	엔드포인트당 하루 1,600건의 통화	매장 위치 및 세부 정보
카트	1.2.3	하루 5,000통화	장바구니 항목 추가/관리
신원	1.2.3	하루 5,000통화	사용자 프로필 정보

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

🏫 기본 워크플로

선호하는 위치를 설정하세요 :
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]
제품 검색 및 추가 :
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]
장바구니 및 주문 관리 :
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 패키지 문서를 읽어보세요.

Kroger MCP Server