willhaben-mcp

willhaben.at 마켓플레이스의 게시물을 AI가 검색하고 광고의 전체 상세 정보를 가져올 수 있게 해 주는 MCP 서버입니다. willhaben의 리버스 엔지니어링된 모바일 앱 API를 래핑하며, 중요한 필드만 AI에게 반환합니다.

도구

search_willhaben(keyword, ...)

마켓플레이스를 검색합니다. category를 전달하면 keyword는 선택 사항입니다.

필터:

• category (id 또는 이름)

• condition (신품, 중고, 리퍼브, ...)

• clothing_size 및 shoe_size

• color, pattern

• brand

• 지역, 판매자 유형, 가격 범위, PayLivery, 최근 48시간

• 정렬 및 페이지네이션

간추린 결과 목록을 반환합니다.

get_ad_detail(ad_id)

한 광고에 대한 모든 정보를 제공합니다. 전체(잘리지 않은) 설명, 모든 이미지, 항목별 속성, 카테고리 경로, 정확한 위치가 포함됩니다. 검색에서 얻은 id에 대해 실행하세요.

list_categories(query, parent_id)

category 필터에 사용할 카테고리 id를 찾습니다.

• query: 전체 트리를 이름으로 검색합니다.

• parent_id: 한 단계 아래로 이동합니다. (둘 다 생략하면 최상위 카테고리를 표시합니다.)

전체 트리(~3500개 카테고리)는 category-tree.json과 함께 서버에 포함되어 제공됩니다.

search_brands(category, term)

브랜드는 카테고리별로 다르며, 카테고리당 1000개 이상 있으므로 자동 완성(type-ahead) 방식입니다. category와 검색어를 전달하면 일치하는 브랜드 id를 받아 search_willhaben(brand=...)에 넘겨 사용하세요.

참고: 상태, 사이즈, 색상, 패턴, 브랜드는 카테고리에 따라 다릅니다. 넓은 카테고리에 적용하면 검색 결과가 0개 나올 수 있으므로, 먼저 특정 하위 카테고리로 좁혀서 사용하세요.

Related MCP server: Secondhand MCP

설정

pip install -r requirements.txt

실행

python main.py

서버는 streamable HTTP로 실행되고, 수신 대기 주소를 출력합니다:

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

MCP 클라이언트는 이 URL을 가리키도록 설정하세요. 호스트, 포트, 경로는 main.py의 상단에 있습니다.

참고

• 상세 API는 정적 앱 토큰으로 보호되어 있으며 HTTP/2에서만 응답합니다. 둘 다 main.py에서 처리됩니다. willhaben이 토큰을 교체하면 앱의 요청 헤더에서 새 토큰을 받아 WH_APPLICATION_TOKEN을 교체하세요.

• category-tree.json은 willhaben 마켓플레이스 카테고리 트리(id, label, parentId, children)의 생성된 스냅샷입니다. main.py는 시작 시 이 스냅샷을 로드해 category 필터와 list_categories에 사용합니다. 분류 체계가 변경되면 다시 크롤링하세요.

• API 상세 정보는 search_api.md에 문서화되어 있습니다.

• 이 서버는 willhaben의 내부 API를 사용하는 비공식 서버입니다. 그에 맞게 무리하게 사용하지 마세요.

면책 조항

이 프로젝트는 독립적이고 비공식적인 프로젝트이며, willhaben과 제휴, 보증, 연관이 없습니다. "willhaben" 및 모든 관련 상표는 각각의 소유자에게 귀속됩니다.

이 프로젝트는 교육 및 연구 목적으로만 제공됩니다. willhaben의 내부 API와 통신하며, 해당 API는 공개용이 아니므로 언제든 깨지거나 바뀔 수 있습니다. 사용 방법에 대한 책임은 사용자에게 있습니다: willhaben의 서비스 이용약관, robots 규칙 및 관련 법률을 준수하고, 서버에 과부하를 주거나 게시물에서 개인 데이터를 처리하지 마세요. 어떠한 보증도 없으며, 사용에 따르는 위험은 본인이 감수하세요.

권리자로서 이 저장소에 대해 우려가 있다면 이슈(issue)를 열어 주세요. 신속하게 답변하겠습니다.

라이선스

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