Skip to main content
Glama
Wallapop MCP Server

Wallapop MCP Server

by AdeiTamayo

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. Blocks in-person-only listings outside your pickup radius and reports the real total (offer + Wallapop protection + shipping)

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)

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_PICKUP_LAT / LNG / RADIUS_KM

Your pickup location — make_offer refuses in-person-only listings outside this radius

WALLAPOP_PROTECTION_PCT / WALLAPOP_SHIPPING_FEE_EUR

Wallapop protection fee % (≈8–10) and shipping fee (≈3–5) used to report the real total of an offer

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.

License

MIT — see LICENSE. Unofficial project, not affiliated with or endorsed by Wallapop.

Available Tools

6 tools
get_listingGet full listing detailsA

Get detailed information about a single Wallapop listing: description, condition, price, images, location, views, favorites, seller id, shipping options. Accepts the numeric listing id, a web slug, or a full item URL. Falls back to server-side rendering when the API fails.

Inputs: itemId (required).

get_sellerGet seller informationA

Get a Wallapop seller profile by numeric user id (from a listing) or by web slug (e.g. 'sergiof-462579195'): rating, review count, sold/published counts, registration date, location.

Inputs: reference (required).

list_categoriesList Wallapop categoriesA

List all marketplace top-level categories with ids and subcategories.

Inputs: no named parameters.

scan_productsScan multiple searches for phone candidatesA

Runs several keyword searches (default nationwide radius) and dedupes results, keeping only in-range, shippable listings and flagging suspicious ones (scam wording or book-slug retitled listings). Returns compact candidate list, ready for get_listing/verify.

Inputs: queries (required), distanceKm, maxResultsPerQuery.

search_productsSearch Wallapop listingsA

Search Wallapop for products with optional filters: category, price range, location (latitude/longitude), radius, sort order. Paginate with the nextPage cursor returned. Reserved listings are filtered out. Returns up to maxResults listings (default 40, capped at 200).

Inputs: keywords (required), orderBy, latitude, maxPrice, +6 more.

server_statusGet MCP server health and auth statusA

Returns whether the server is configured for public or authenticated use, whether a session is loaded, and whether browser fallback is available.

Inputs: no named parameters.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4/5.0

    Scored across 6 tools

    Disambiguation4/5

    Most tools are clearly distinct: search_products, get_listing, get_seller, list_categories, and server_status each target a different resource or action. The main ambiguity is between search_products and scan_products, though scan_products is clearly positioned as a specialized multi-keyword search with deduplication.

    Naming Consistency4/5

    The naming pattern is largely consistent: search_products, get_listing, get_seller, list_categories, and scan_products all follow verb_noun naming. server_status breaks the pattern slightly by using a noun phrase instead of a get_ or status_ verb, but it is still readable and predictable.

    Tool Count5/5

    Six tools is well-scoped for a marketplace browsing/searching MCP server. Each tool covers a meaningful capability without bloat, and the count feels appropriate for the server's purpose.

    Completeness4/5

    The core browsing flow is covered: search listings, get listing details, get seller profiles, and list categories. Minor gaps exist such as not being able to list a seller's active listings or perform authenticated actions, but those are not necessarily core to this server's stated scope.

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      B
      quality
      A
      maintenance
      MCP server for automating Xianyu (Goofish) marketplace operations: publish, manage items, handle IM messages, and more via CLI or AI agents.
      17
      1,060 PyPI
      498
      Apache 2.0
    • A
      license
      A
      quality
      C
      maintenance
      MCP server for interacting with Bazos.cz, Bazos.sk, Bazos.at, and Bazos.pl. Supports searching ads, retrieving ad details, and fetching user ratings.
      3
      101 npm
      4
      AGPL 3.0
    • A
      license
      Not graded
      quality
      C
      maintenance
      An MCP server for Vinted search and analysis that provides tools to search listings, fetch item details, inspect seller profiles, compare prices across countries, and surface trending items.
      36
      AGPL 3.0