Servidor MCP de Wallapop

Servidor MCP híbrido y no oficial para el mercado de Wallapop, construido en TypeScript.

• HTTP principal: llamadas de ingeniería inversa a los endpoints privados v3 de api.wallapop.com

• Respaldo SSR: extracción de __NEXT_DATA__ de las páginas de es.wallapop.com (detalles de artículos, perfiles de vendedores)

• Respaldo Playwright: navegador con interfaz fuera de pantalla como último recurso (el CDN de Wallapop bloquea Chrome sin interfaz)

• Autenticación: opcional con correo/contraseña o importación de cookies del navegador para favoritos, búsquedas guardadas, chat y ofertas (refresco de token + persistencia de sesión)

No oficial y sin afiliación. Utiliza la API no documentada de Wallapop, que puede cambiar o bloquear el tráfico en cualquier momento: úsalo bajo tu propio riesgo, mantén un volumen de solicitudes bajo y respeta sus Términos de Servicio.

Herramientas

Related MCP server: Bazos-MCP

Inicio rápido

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

Conectar a un cliente MCP

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

# Inspector (browse tools interactively)
npm run inspector

Configuración (.env, ver .env.example)

Nota: WALLAPOP_EMAIL/WALLAPOP_PASSWORD pueden fallar para cuentas con MFA o flujos de Keycloak — en ese caso, exporta cookies desde un navegador con sesión iniciada a WALLAPOP_COOKIES_FILE (una matriz JSON de objetos de cookie) y el servidor las usará directamente.

Cómo funciona

Búsqueda (flujo de API en dos pasos)

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

2. GET /api/v3/search/section (40 artículos/página) → meta.next_page JWT; el servidor empaqueta search_id + cursor en un token nextPage opaco para que los clientes simplemente lo devuelvan.

Chat y ofertas

• Los mensajes se envían a través del canal en tiempo real (PubNub) y también llegan a la API de bandeja de entrada (/bff/messaging/inbox) — ambos verificados de extremo a extremo.

• Las ofertas se crean mediante POST /api/v3/delivery/buyer/offers con un id de oferta generado por el cliente; los vendedores las reciben en la conversación.

Autenticación

• Intenta POST /api/v3/access/login → almacena tokens de acceso/refresco + cookies en el archivo de sesión, refresca mediante POST /api/v3/access/refresh cuando el JWT está a punto de expirar.

• Recurre a un inicio de sesión automatizado del navegador; los desafíos MFA se detectan y se muestran como un error (complétalo manualmente, luego exporta las cookies a WALLAPOP_COOKIES_FILE).

Cadena de respaldo

1. Solicitud a la API con cabeceras similares a las de un navegador, rotación de UA, retroceso exponencial en 429 y reintento con X-Signature en 403

2. Extracción de HTML SSR (es.wallapop.com/item/..., /user/...) — datos más ricos para vendedores (valoraciones, contadores)

3. Chrome con interfaz fuera de pantalla mediante Playwright (captura las respuestas XHR de api.wallapop.com) — el CDN de Wallapop bloquea el modo sin interfaz, así que nunca uses WALLAPOP_BROWSER=chromium sin descargas manuales del navegador; auto prefiere Chrome/Edge instalados

Notas y limitaciones conocidas

• El filtrado por precio (minPrice/maxPrice) y por radio (distance_in_km) de search_products son parámetros del lado de la API.

• favorite_listing/unfavorite_listing usan candidatos de endpoint de mejor esfuerzo — verifica con tu cuenta; los endpoints cambian.

• El condition del artículo solo está disponible de forma fiable mediante get_listing (los resultados de búsqueda normalmente lo omiten).

• Algunos vendedores desactivan las ofertas — make_offer muestra un error 409 en ese caso.