geizhals-mcp

AI가 Geizhals의 가격 비교 데이터를 검색할 수 있게 해주는 MCP 서버입니다. 제품, 최저가, 가격 내역, 평점, 카테고리를 다룹니다. Geizhals 모바일 앱의 API(api.geizhals.net/gh/v9)를 래핑하여 AI가 필요로 하는 중요한 필드를 반환합니다.

주요 기능

• 모든 매장의 최저가
  제품을 찾으면 최저가, 전체 가격 범위, 별점, 테스트 리뷰 수를 단일 상품 목록이 아니라 모든 Geizhals 판매처를 대상으로 집계한 결과로 제공합니다.

• 구매 시점 파악
  전체 가격 내역과 현재 할인 상품(Schnäppchen)을 가져옵니다. 할인율이 큰 순서대로 정렬할 수 있어 "지금이 저렴할 때일까, 기다려야 할까"라는 질문에 답할 수 있습니다.

• 키워드에서 카테고리까지
  자유 텍스트로 검색하거나 서버에 포함되어 있는 전체 Geizhals 카테고리 트리(2,200개 이상 카테고리)를 탐색하여 원하는 항목으로 정확히 들어간 뒤, 후보 제품들을 나란히 비교할 수 있습니다.

Related MCP server: geizhals-mcp

도구

search_geizhals(query, ...)

키워드로 제품을 검색합니다. 국가(loc/hloc), 카테고리, 제조사 필터를 지원하며 정렬과 페이징도 가능합니다. 검색 결과와 함께 패싯 집계(카테고리, 제조사, 가격 범위)를 반환해 검색을 더 세밀하게 다듬을 수 있습니다.

get_product(product_id)

제품 하나의 전체 상세 정보: 이름, 평점, 최저가 범위, 이미지, 판매 링크, 테스트 리뷰 수를 반환합니다.

get_price_history(product_id, days=31)

최소/최대/현재 가격 요약과 원본 [timestamp, price, flag] 시계열 데이터를 반환합니다.

get_product_ratings(product_id)

평균 평점, 평점 총계, 별점별 개수와 리뷰 링크를 반환합니다.

browse_category(category, ...)

카테고리 코드로 해당 카테고리의 제품 목록을 가격 범위와 정렬 옵션과 함께 반환합니다.

compare_products(product_ids)

여러 제품을 나란히 비교합니다.

get_deals(sort="percent", ...)

현재 가격 인하 상품, 즉 최저가가 방금 낮아진 제품들을 할인율과 할인 금액과 함께 표시합니다. 할인 폭이 가장 큰 percent 기준과 price(가격), latest(최신), popularity(인기), top 할인 기준으로 정렬할 수 있으며 min_discount_percent로 필터링할 수 있습니다.

list_categories(query)

Geizhals의 카테고리 트리를 탐색해 browse_category에 전달할 카테고리 코드를 찾습니다. 전체 트리는 data/categories.json 파일로 서버에 포함되어 있습니다.

설치

Python 3.9+가 필요합니다.

pip install -r requirements.txt

실행

python main.py

서버는 streamable HTTP로 시작되며 수신 주소를 출력합니다.

Starting geizhals-mcp server on http://127.0.0.1:8000/mcp

MCP 클라이언트가 해당 URL을 가리키게 하면 됩니다. 호스트, 포트, 경로는 main.py 상단에 정의되어 있습니다.

Claude Desktop에서 사용하기

Claude Desktop은 stdio로 MCP 서버를 실행하므로, 이 HTTP 서버를 mcp-remote를 사용해 연결할 수 있습니다. Node.js가 필요합니다.

1. 서버(python main.py)를 시작하고 계속 실행해 둡니다.

2. Claude Desktop에서 Settings > Developer > Edit Config를 열면 claude_desktop_config.json 파일이 보입니다. 파일을 열고 geizhals 항목을 추가하세요:

   {
     "mcpServers": {
       "geizhals": {
         "command": "cmd",
         "args": ["/c", "npx", "-y", "mcp-remote", "http://127.0.0.1:8000/mcp"]
       }
     }
   }

   macOS/Linux에서는 Windows용 래퍼를 제거하고 "command": "npx"에 "args": ["-y", "mcp-remote", "http://127.0.0.1:8000/mcp"]를 사용하세요.

3. 파일을 저장하고 Claude Desktop을 재시작합니다.

참고 사항

• data/categories.json은 Geizhals 카테고리 트리(제목, id, 하위 항목)의 스냅샷입니다. main.py는 list_categories를 위해 이 파일을 불러옵니다.

• coverage.json은 위 배지에 표시된 카탈로그 수치를 담고 있습니다. scripts/update_coverage.py가 Geizhals 홈페이지에서 이 수치를 갱신하고, 일일 GitHub Action이 변경 사항을 커밋합니다.

• API 세부 사항은 search_api.md에 문서화되어 있습니다.

• 이 프로젝트는 Geizhals의 비공식 내부 모바일 API를 사용합니다. 과부화되지 않도록 적절히 사용하세요.

문제 해결

403 invalid request_fingerprint in payload — main.py에 있는 HMAC 시크릿 또는 서명 방식(GH_HMAC_SECRET, request_fingerprint, API_HOST)이 현재 Geizhals 앱이 전송하는 값과 더 이상 일치하지 않는 경우입니다. 앱을 리버스 엔지니어링해 하드코딩된 값이므로, Geizhals가 시크릿을 교체하거나 방식이 변경되면 불일치가 발생할 수 있습니다.

면책 조항

이 프로젝트는 독립적이고 비공식적인 프로젝트이며, Geizhals와 제휴, 보증, 연결 관계가 없습니다. "Geizhals" 및 관련 상표는 각 소유자의 자산입니다.

이 프로젝트는 교육 및 연구 목적으로만 제공됩니다. 공개용으로 만들지 않은 Geizhals 내부 API에 접근하며, 언제든지 중단되거나 변경될 수 있습니다. 사용 방법에 대한 책임은 사용자 본인에게 있습니다. Geizhals의 이용약관, robots 규칙 및 관련 법률을 준수하고 서버에 과부화를 주지 마세요.

라이선스

MIT LICENSE. 보증 없이 "있는 그대로" 제공됩니다.