kroger-mcp

Model Context Protocol (MCP)를 통해 Claude와 같은 AI 어시스턴트에게 Kroger의 식료품 쇼핑 기능에 대한 접근 권한을 제공하는 FastMCP 서버입니다. 이 서버는 AI 어시스턴트가 kroger-api python 라이브러리를 통해 매장을 찾고, 제품을 검색하며, 쇼핑 카트를 관리하고, Kroger의 포괄적인 식료품 데이터에 접근할 수 있도록 합니다.

이 MCP 서버를 Claude와 함께 사용하여 매장을 검색하고, 제품을 찾고, 품목을 카트에 추가하는 방법:

kroger_mcp_demo_processed.mp4

최근 변경 사항이 포함된 변경 로그(changelog)는 여기에 있습니다.

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

• 개발자 계정 생성
• 애플리케이션 등록
• CLIENT_ID, CLIENT_SECRET을 받고 REDIRECT_URI를 설정하세요.

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

PyPI에 게시되면, 저장소를 클론(clone)하지 않고도 uvx를 사용하여 패키지를 직접 실행할 수 있습니다:

Claude Desktop의 설정 파일을 편집하세요:

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

Linux: ~/.config/Claude/claude_desktop_config.json

Windows: %APPDATA%/Claude/claude_desktop_config.json

{
"mcpServers": {
"kroger": {
...

이 방법의 장점:

• 필요한 경우 PyPI에서 패키지를 자동으로 설치합니다.
• 서버 실행을 위한 격리된 환경을 생성합니다.
• 최신 버전으로 업데이트하기가 쉽습니다.
• 로컬 저장소 클론을 유지 관리할 필요가 없습니다.

먼저, 로컬에 클론하세요:

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

그 다음, Claude Desktop의 설정 파일을 편집하세요:

{
"mcpServers": {
"kroger": {
...

# uv로 설치 (권장)
uv pip install kroger-mcp
# 또는 pip로 설치
...

# 저장소 클론
git clone https://github.com/CupOfOwls/kroger-mcp
cd kroger-mcp
...

.env 파일을 생성하세요

프로젝트 루트에 파일을 생성하거나 JSON 설정을 통해 환경 변수 (env values)를 전달하세요:

# 필수: Kroger API 자격 증명 (credentials)
KROGER_CLIENT_ID=your_client_id_here
KROGER_CLIENT_SECRET=your_client_secret_here
...

# uv 사용 시 (권장)
uv run kroger-mcp
# uvx 사용 시 (설치 없이 PyPI에서 직접 실행)
...

쇼핑 경로 (Shopping Path): 식료품 목록을 위한 매장 내 최적 경로 찾기
약국 확인 (Pharmacy Check): 선호하는 위치의 약국이 영업 중인지 확인
매장 선택 (Store Selection): 사용자가 선호하는 Kroger 매장을 설정하도록 지원
레시피 쇼핑 (Recipe Shopping): 레시피를 찾고 재료를 장바구니에 추가

도구 (Tool)	설명 (Description)	인증 필요 (Auth Required)
search_locations	우편번호 (zip code) 근처의 Kroger 매장 찾기	아니요
get_location_details	특정 매장에 대한 상세 정보 가져오기	아니요
set_preferred_location	향후 작업을 위한 선호 매장 설정	아니요
get_preferred_location	현재 설정된 선호 매장 가져오기	아니요
check_location_exists	위치 ID (location ID)가 유효한지 확인	아니요

도구 (Tool)	설명 (Description)	인증 필요 (Auth Required)
search_products	이름, 브랜드 또는 기타 기준으로 제품 검색	아니요
get_product_details	가격을 포함한 상세 제품 정보 가져오기	아니요
search_products_by_id	특정 제품 ID (product ID)로 제품 찾기	아니요
get_product_images	특정 관점(앞면, 뒷면 등)의 제품 이미지 가져오기	아니요

도구 (Tool)	설명 (Description)	인증 필요 (Auth Required)
add_items_to_cart	단일 항목을 장바구니에 추가	예
bulk_add_to_cart	한 번의 작업으로 여러 항목을 장바구니에 추가	예
view_current_cart	현재 로컬 장바구니 추적 중인 항목 보기	아니요
remove_from_cart	로컬 장바구니 추적에서 항목 제거	아니요
clear_current_cart	로컬 장바구니 추적에서 모든 항목 삭제	아니요
mark_order_placed	현재 장바구니를 주문 내역으로 이동	아니요
view_order_history	완료된 주문 내역 보기	아니요

도구 (Tool)	설명 (Description)	인증 필요 (Auth Required)
list_chains	모든 Kroger 소유 체인 목록 가져오기	아니요
get_chain_details	특정 체인의 상세 정보 가져오기	아니요
check_chain_exists	체인 존재 여부 확인	아니요
list_departments	모든 매장 부서 목록 가져오기	아니요
get_department_details	특정 부서의 상세 정보 가져오기	아니요
check_department_exists	부서 존재 여부 확인	아니요

도구 (Tool)	설명 (Description)	인증 필요 (Auth Required)
get_user_profile	인증된 사용자의 프로필 정보 가져오기	예
test_authentication	인증 토큰의 유효성 테스트	예
get_authentication_info	상세 인증 상태 가져오기	예
force_reauthenticate	토큰을 삭제하고 강제로 재인증 수행	아니요

도구 (Tool)	설명 (Description)	인증 필요 (Auth Required)
get_current_datetime	현재 시스템 날짜 및 시간 가져오기	아니요

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

파일 (File): kroger_cart.json

내용 (Contents): 타임스탬프가 포함된 현재 장바구니 항목
자동 (Automatic): 자동으로 생성 및 업데이트됨

파일 (File): kroger_order_history.json

내용 (Contents): 주문 시점 타임스탬프가 포함된 과거 주문 내역
사용법 (Usage): mark_order_placed를 사용하여 완료된 장바구니를 내역으로 이동

조회 전용 (View Only): remove_from_cart 및 clear_current_cart 도구는 로컬 추적에만 영향을 미치며, 실제 Kroger 장바구니에는 영향을 주지 않습니다.
로컬 동기화 (Local Sync): 사용자가 Kroger 앱/웹사이트에서 이미 장바구니 항목을 삭제한 경우에만 이 도구들을 사용하십시오.
단방향 (One-Way): 항목을 Kroger 장바구니에 추가할 수는 있지만, 퍼블릭 API (Public API)를 통해 삭제할 수는 없습니다. 파트너 API (Partner API)를 사용하면 이러한 작업이 가능하지만, 이를 위해서는 Kroger와 계약을 체결해야 합니다.

API	버전 (Version)	속도 제한 (Rate Limit)	비고 (Notes)
Authorization	1.0.13	특정 제한 없음	토큰 관리 (Token management)
Products	1.2.4	일일 10,000회 호출	검색 및 제품 상세 정보
Locations	1.2.2	엔드포인트당 일일 1,600회 호출	매장 위치 및 상세 정보
Cart	1.2.3	일일 5,000회 호출	장바구니 항목 추가/관리
Identity	1.2.3	일일 5,000회 호출	사용자 프로필 정보

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

선호 위치 설정 (Set up a preferred location):사용자: "90274 근처의 Kroger 매장을 찾아줘" 어시스턴트: [search_locations 도구 사용] 사용자: "첫 번째 매장을 내 선호 위치로 설정해줘" 어시스턴트: [set_preferred_location 도구 사용]

제품 검색 및 추가 (Search and add products):사용자: "내 장바구니에 우유를 추가해줘" 어시스턴트: [search_products 사용 후, add_items_to_cart 사용] 사용자: "빵, 계란, 치즈를 내 장바구니에 추가해줘" 어시스턴트: [각 제품에 대해 search_products 사용 후, bulk_add_to_cart 사용]

장바구니 및 주문 관리 (Manage cart and orders):사용자: "내 장바구니에 무엇이 들어있지?" 어시스턴트: [로컬 메모리를 확인하기 위해 view_current_cart 도구 사용] 사용자: "Kroger 웹사이트에서 주문을 완료했어" 어시스턴트: [mark_order_placed 도구를 사용하여 현재 장바구니를 주문 내역으로 이동]

Claude가 사용자의 Kroger 계정을 수정하려고 시도할 때, 인증을 처리하고 Claude가 장바구니에서 항목을 추가/삭제할 수 있도록 허용하는 링크를 브라우저에 삽입하라는 요청을 받게 됩니다. 인증을 시작하기 위해 이 링크를 브라우저에 붙여넣기 전에, 이미 Kroger 계정(이는 Kroger 개발자 계정과는 다릅니다)을 생성했는지 확인하십시오.

기여는 언제나 환영합니다! 자유롭게 Pull Request를 제출해 주세요. 주요 변경 사항의 경우, 변경하고자 하는 내용을 논의하기 위해 먼저 Issue를 생성해 주세요.

이 프로젝트는 MIT 라이선스(MIT License) 하에 라이선스가 부여됩니다 - 자세한 내용은 LICENSE 파일을 참조하세요.

Kroger API에 관한 질문은 Kroger Developer Portal을 방문하거나 kroger-api 패키지 문서를 읽어보시기 바랍니다.