Wallapop MCP 서버

Wallapop 마켓플레이스를 위한 하이브리드, 비공식 MCP 서버로, TypeScript로 작성되었습니다.

• HTTP 기본: 비공개 api.wallapop.com v3 엔드포인트에 대한 리버스 엔지니어링 호출

• SSR 폴백: es.wallapop.com 페이지의 __NEXT_DATA__ 스크래핑 (아이템 상세, 판매자 프로필)

• Playwright 폴백: 최후의 수단으로 화면 밖 헤드 브라우저 (Wallapop의 CDN이 헤드리스 Chrome을 차단함)

• 인증: 즐겨찾기, 저장된 검색, 채팅 및 제안을 위한 선택적 이메일/비밀번호 또는 브라우저 쿠키 가져오기 (토큰 갱신 + 세션 지속)

비공식이며 제휴가 아닙니다. Wallapop의 문서화되지 않은 API를 사용하며, 이는 언제든지 변경되거나 트래픽을 차단할 수 있습니다 — 사용에 따른 책임은 본인에게 있으며, 요청량을 낮게 유지하고 서비스 이용약관을 준수하십시오.

도구

Related MCP server: Bazos-MCP

빠른 시작

git clone <this-repo>
cd WallpopMCP
npm install
npm run build
cp .env.example .env   # fill in your keys (see Configuration)
npm run smoke          # live sanity check against the API

MCP 클라이언트에 연결

# Claude Code (stdio)
claude mcp add wallapop -- node /absolute/path/to/WallpopMCP/dist/index.js

# Inspector (browse tools interactively)
npm run inspector

구성 (.env, .env.example 참조)

참고: WALLAPOP_EMAIL/WALLAPOP_PASSWORD는 MFA 또는 Keycloak 흐름이 있는 계정에서는 실패할 수 있습니다 — 이 경우 로그인된 브라우저에서 쿠키를 WALLAPOP_COOKIES_FILE (쿠키 객체의 JSON 배열)로 내보내면 서버가 이를 직접 사용합니다.

작동 방식

검색 (2단계 API 흐름)

1. GET /api/v3/search/components → search_id

2. GET /api/v3/search/section (페이지당 40개 항목) → meta.next_page JWT; 서버는 search_id + 커서를 불투명한 nextPage 토큰으로 패키징하여 클라이언트가 그냥 다시 전달하도록 합니다.

채팅 및 제안

• 메시지는 실시간 채널 (PubNub)을 통해 전송되며 받은 편지함 API (/bff/messaging/inbox)에도 도달합니다 — 둘 다 종단 간 검증됨.

• 제안은 클라이언트 생성 제안 ID와 함께 POST /api/v3/delivery/buyer/offers를 통해 생성됩니다; 판매자는 대화에서 이를 받습니다.

인증

• POST /api/v3/access/login 시도 → 액세스/리프레시 토큰 + 쿠키를 세션 파일에 저장, JWT가 만료되기 직전에 POST /api/v3/access/refresh를 통해 갱신.

• 자동 브라우저 로그인으로 폴백; MFA 챌린지가 감지되어 오류로 표시됩니다 (수동으로 완료한 다음 쿠키를 WALLAPOP_COOKIES_FILE로 내보내십시오).

폴백 체인

1. 브라우저 유사 헤더, UA 회전, 429에 대한 지수 백오프, 403에 대한 X-Signature 재시도가 있는 API 요청

2. SSR HTML 스크래핑 (es.wallapop.com/item/..., /user/...) — 판매자에게 더 풍부한 데이터 (평점, 카운터)

3. Playwright를 통한 화면 밖 헤드 Chrome (api.wallapop.com XHR 응답 캡처) — Wallapop의 CDN이 헤드리스 모드를 차단하므로 수동 브라우저 다운로드 없이 WALLAPOP_BROWSER=chromium을 사용하지 마십시오; auto는 설치된 Chrome/Edge를 선호합니다

참고 사항 및 알려진 제한

• search_products 가격 필터 (minPrice/maxPrice) 및 반경 필터 (distance_in_km)는 API 측 매개변수입니다.

• favorite_listing/unfavorite_listing은 최선 노력 엔드포인트 후보를 사용합니다 — 계정으로 확인하십시오; 엔드포인트는 변경될 수 있습니다.

• 아이템 condition은 get_listing을 통해서만 안정적으로 사용할 수 있습니다 (검색 결과는 일반적으로 생략).

• 일부 판매자는 제안을 비활성화합니다 — 이 경우 make_offer는 409 오류를 표시합니다.