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

Tool	Auth	Description
search_products	–	Keyword search with category / price / location / radius / sort filters, cursor pagination (nextPage), reserved items filtered out
scan_products	–	Multi-query keyword scan with dedupe, price filtering and scam-flagging (shippable listings)
get_listing	–	Full listing detail: description, condition, price, images, views, favorites, seller, shipping
get_seller	–	Seller profile by id or web slug: rating (0–100), sold/published counts, registration date, location
list_categories	–	Marketplace category tree with ids
server_status	–	Health / auth / browser-fallback status
favorite_listing / unfavorite_listing	required	Favorites by numeric id, web slug or item URL (API + browser fallback)
get_saved_searches / create_saved_search / delete_saved_search	required	Saved search alerts
list_conversations	required	Chat inbox: other user, item, unread count, last message
get_messages	required	Full message history of a conversation
send_message	required	Send a chat message (real-time channel)
make_offer	required	Send a purchase offer (EUR) — seller gets it in chat and can accept/reject

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)

Variable	Purpose
WALLAPOP_EMAIL / WALLAPOP_PASSWORD	Enable auth tools (favorites, saved searches, chat, offers)
WALLAPOP_COOKIES_FILE	Optional JSON array of browser cookies ([{ name, value }]) exported from a logged-in session — the most reliable authenticated path
WALLAPOP_DEFAULT_LAT / LNG / DISTANCE_KM	Default search location (Barcelona center)
WALLAPOP_SESSION_FILE	Token/cookie persistence (default ./wallapop-session.json, gitignored)
WALLAPOP_RATE_DELAY_MS	Min delay between API calls (default 600)
WALLAPOP_MAX_RESULTS	Search results cap, 1–200 (default 200)
WALLAPOP_BROWSER	auto (default) | chrome | msedge | chromium | off

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.