Wallapop MCP Server

Hybrid, unofficial MCP server for the Wallapop marketplace, built in TypeScript.

• HTTP primary: reverse-engineered calls to the private api.wallapop.com v3 endpoints

• SSR fallback: __NEXT_DATA__ scraping of es.wallapop.com pages (item details, seller profiles)

• Playwright fallback: off-screen headed browser as last resort (Wallapop's CDN blocks headless Chrome)

• Authentication: optional email/password or browser-cookie import for favorites, saved searches, chat and offers (token refresh + session persistence)

Unofficial and unaffiliated. Uses Wallapop's undocumented API, which can change or block traffic at any time — use at your own risk, keep request volume low, and respect their Terms of Service.

Tools

Related MCP server: Bazos-MCP

Quick start

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

Connect to an MCP client

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

# Inspector (browse tools interactively)
npm run inspector

Configuration (.env, see .env.example)

Note: WALLAPOP_EMAIL/WALLAPOP_PASSWORD may fail for accounts with MFA or Keycloak flows — in that case export cookies from a logged-in browser into WALLAPOP_COOKIES_FILE (a JSON array of cookie objects) and the server will use them directly.

How it works

Search (two-step API flow)

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

2. GET /api/v3/search/section (40 items/page) → meta.next_page JWT; the server packs search_id + cursor into an opaque nextPage token so clients just pass it back.

Chat & offers

• Messages are sent through the real-time channel (PubNub) and also land in the inbox API (/bff/messaging/inbox) — both verified end-to-end.

• Offers are created via POST /api/v3/delivery/buyer/offers with a client-generated offer id; sellers receive them in the conversation.

Authentication

• Tries POST /api/v3/access/login → stores access/refresh tokens + cookies to the session file, refreshes via POST /api/v3/access/refresh when the JWT is about to expire.

• Falls back to an automated browser login; MFA challenges are detected and surfaced as an error (complete it manually, then export cookies to WALLAPOP_COOKIES_FILE).

Fallback chain

1. API request with browser-like headers, UA rotation, exponential back-off on 429, and X-Signature retry on 403

2. SSR HTML scraping (es.wallapop.com/item/..., /user/...) — richer data for sellers (ratings, counters)

3. Off-screen headed Chrome via Playwright (captures api.wallapop.com XHR responses) — Wallapop's CDN blocks headless mode, so never use WALLAPOP_BROWSER=chromium without manual browser downloads; auto prefers installed Chrome/Edge

Notes and known limits

• search_products price filtering (minPrice/maxPrice) and radius filtering (distance_in_km) are API-side parameters.

• favorite_listing/unfavorite_listing use best-effort endpoint candidates — verify with your account; endpoints change.

• Item condition is only reliably available via get_listing (search results usually omit it).

• Some sellers disable offers — make_offer surfaces a 409 error in that case.