Wallapop MCP Server
This server provides an unofficial interface to Wallapop marketplace, enabling product search/scanning, listing and seller details, category browsing, and authenticated actions like favorites, saved searches, chat, and offers.
Search and scan products with filters (keywords, category, price, location/radius, sort) and pagination; scan dedupes results and flags suspicious listings.
Get full listing details and seller profiles (rating, sold/published counts, registration date, location).
List the marketplace category tree with ids.
Check server health, auth status, and browser-fallback availability.
Authenticated tools: favorite/unfavorite listings, manage saved searches, list conversations, view/send messages, and make purchase offers (with pickup-radius enforcement and estimated total cost).
Uses API, SSR scraping, and browser automation fallbacks for resilience.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Wallapop MCP Server search for vintage cameras under 200 euros in Barcelona"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Wallapop MCP Server
Hybrid, unofficial MCP server for the Wallapop marketplace, built in TypeScript.
HTTP primary: reverse-engineered calls to the private
api.wallapop.comv3 endpointsSSR fallback:
__NEXT_DATA__scraping ofes.wallapop.compages (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 |
| – | Keyword search with category / price / location / radius / sort filters, cursor pagination ( |
| – | Multi-query keyword scan with dedupe, price filtering and scam-flagging (shippable listings) |
| – | Full listing detail: description, condition, price, images, views, favorites, seller, shipping |
| – | Seller profile by id or web slug: rating (0–100), sold/published counts, registration date, location |
| – | Marketplace category tree with ids |
| – | Health / auth / browser-fallback status |
| required | Favorites by numeric id, web slug or item URL (API + browser fallback) |
| required | Saved search alerts |
| required | Chat inbox: other user, item, unread count, last message |
| required | Full message history of a conversation |
| required | Send a chat message (real-time channel) |
| 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 APIConnect 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 inspectorConfiguration (.env, see .env.example)
Variable | Purpose |
| Enable auth tools (favorites, saved searches, chat, offers) |
| Optional JSON array of browser cookies ( |
| Default search location (Barcelona center) |
| Token/cookie persistence (default |
| Min delay between API calls (default 600) |
| Search results cap, 1–200 (default 200) |
| Your pickup location — |
| Wallapop protection fee % (≈8–10) and shipping fee (≈3–5) used to report the real total of an offer |
|
|
Note:
WALLAPOP_EMAIL/WALLAPOP_PASSWORDmay fail for accounts with MFA or Keycloak flows — in that case export cookies from a logged-in browser intoWALLAPOP_COOKIES_FILE(a JSON array of cookie objects) and the server will use them directly.
How it works
Search (two-step API flow)
GET /api/v3/search/components→search_idGET /api/v3/search/section(40 items/page) →meta.next_pageJWT; the server packssearch_id+ cursor into an opaquenextPagetoken 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/offerswith 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 viaPOST /api/v3/access/refreshwhen 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
API request with browser-like headers, UA rotation, exponential back-off on 429, and
X-Signatureretry on 403SSR HTML scraping (
es.wallapop.com/item/...,/user/...) — richer data for sellers (ratings, counters)Off-screen headed Chrome via Playwright (captures
api.wallapop.comXHR responses) — Wallapop's CDN blocks headless mode, so never useWALLAPOP_BROWSER=chromiumwithout manual browser downloads;autoprefers installed Chrome/Edge
Notes and known limits
search_productsprice filtering (minPrice/maxPrice) and radius filtering (distance_in_km) are API-side parameters.favorite_listing/unfavorite_listinguse best-effort endpoint candidates — verify with your account; endpoints change.Item
conditionis only reliably available viaget_listing(search results usually omit it).Some sellers disable offers —
make_offersurfaces a 409 error in that case.
License
MIT — see LICENSE. Unofficial project, not affiliated with or endorsed by Wallapop.
Available Tools
6 toolsget_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
Scored across 6 tools
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.
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.
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.
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
Hosted WhatsApp MCP server: read, search and reply to your own WhatsApp chats from your AI.
Your own WhatsApp as an MCP server: read, search and send from any MCP client.
Official SerpApi MCP server for Google, Bing, and other search engines.
Related MCP Servers
- AlicenseBqualityAmaintenanceMCP server for automating Xianyu (Goofish) marketplace operations: publish, manage items, handle IM messages, and more via CLI or AI agents.171,060 PyPI498Apache 2.0
- AlicenseAqualityCmaintenanceMCP server for interacting with Bazos.cz, Bazos.sk, Bazos.at, and Bazos.pl. Supports searching ads, retrieving ad details, and fetching user ratings.3101 npm4AGPL 3.0
- AlicenseNot gradedqualityCmaintenanceAn 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.36AGPL 3.0
- FlicenseBqualityDmaintenanceRead-only MCP server for WhatsApp Web allowing listing chats and reading recent messages, without sending or mutating WhatsApp state.3-