Wallapop MCP Server
Wallapop MCP Server
为 Wallapop 市场构建的混合型非官方 MCP 服务器,使用 TypeScript 编写。
HTTP 主通道:对私有
api.wallapop.comv3 端点进行逆向工程调用SSR 回退:抓取
es.wallapop.com页面中的__NEXT_DATA__(商品详情、卖家资料)Playwright 回退:最后手段是使用屏幕外的有头浏览器(Wallapop 的 CDN 会阻止无头 Chrome)
身份验证:可选邮箱/密码或浏览器 Cookie 导入,用于收藏、已保存搜索、聊天和出价(令牌刷新 + 会话持久化)
非官方且与 Wallapop 无关联。使用 Wallapop 未记录的 API,该 API 可能随时更改或阻止流量——请自行承担使用风险,保持较低的请求量,并遵守其服务条款。
工具
工具 | 认证 | 描述 |
| – | 关键词搜索,支持类别 / 价格 / 位置 / 半径 / 排序筛选,游标分页( |
| – | 多关键词扫描,支持去重、价格筛选和诈骗标记(可配送商品) |
| – | 完整商品详情:描述、成色、价格、图片、浏览量、收藏数、卖家、配送 |
| – | 按 id 或网页 slug 获取卖家资料:评分(0–100)、已售/在售数量、注册日期、位置 |
| – | 带 id 的市场类别树 |
| – | 健康 / 认证 / 浏览器回退状态 |
| 必需 | 按数字 id、网页 slug 或商品 URL 收藏/取消收藏(API + 浏览器回退) |
| 必需 | 已保存的搜索提醒 |
| 必需 | 聊天收件箱:对方用户、商品、未读数、最后一条消息 |
| 必需 | 某个会话的完整消息历史 |
| 必需 | 发送聊天消息(实时通道) |
| 必需 | 发送购买出价(EUR)——卖家会在聊天中收到,并可接受/拒绝 |
Related MCP server: Bazos-MCP
快速开始
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连接到 MCP 客户端
# Claude Code (stdio)
claude mcp add wallapop -- node /absolute/path/to/WallpopMCP/dist/index.js# Inspector (browse tools interactively)
npm run inspector配置(.env,参见 .env.example)
变量 | 用途 |
| 启用认证工具(收藏、已保存搜索、聊天、出价) |
| 可选:从已登录会话导出的浏览器 Cookie 的 JSON 数组( |
| 默认搜索位置(巴塞罗那市中心) |
| 令牌/Cookie 持久化(默认 |
| API 调用之间的最小延迟(默认 600) |
| 搜索结果上限,1–200(默认 200) |
|
|
注意:对于启用 MFA 或 Keycloak 流程的账户,
WALLAPOP_EMAIL/WALLAPOP_PASSWORD可能会失败——在这种情况下,请从已登录的浏览器中将 Cookie 导出到WALLAPOP_COOKIES_FILE(一个 Cookie 对象的 JSON 数组),服务器将直接使用它们。
工作原理
搜索(两步 API 流程)
GET /api/v3/search/components→search_idGET /api/v3/search/section(每页 40 条)→meta.next_pageJWT;服务器将search_id+ 游标打包成一个不透明的nextPage令牌,客户端只需将其传回即可。
聊天与出价
消息通过实时通道(PubNub)发送,同时也会进入收件箱 API(
/bff/messaging/inbox)——两者均已端到端验证。出价通过
POST /api/v3/delivery/buyer/offers创建,使用客户端生成的出价 id;卖家会在会话中收到。
身份验证
尝试
POST /api/v3/access/login→ 将访问/刷新令牌 + Cookie 存储到会话文件中,当 JWT 即将过期时通过POST /api/v3/access/refresh刷新。回退到自动化浏览器登录;检测到 MFA 挑战时会作为错误提示(请手动完成,然后将 Cookie 导出到
WALLAPOP_COOKIES_FILE)。
回退链
API 请求,使用类似浏览器的请求头、UA 轮换、429 时指数退避,以及 403 时
X-Signature重试SSR HTML 抓取(
es.wallapop.com/item/...、/user/...)——为卖家提供更丰富的数据(评分、计数)通过 Playwright 使用屏幕外的有头 Chrome(捕获
api.wallapop.com的 XHR 响应)——Wallapop 的 CDN 会阻止无头模式,因此切勿在未手动下载浏览器的情况下使用WALLAPOP_BROWSER=chromium;auto优先使用已安装的 Chrome/Edge
注意事项与已知限制
search_products的价格筛选(minPrice/maxPrice)和半径筛选(distance_in_km)是 API 侧参数。favorite_listing/unfavorite_listing使用尽力而为的候选端点——请用你的账户验证;端点会变化。商品的
condition只能通过get_listing可靠获取(搜索结果通常会省略它)。部分卖家会禁用出价——此时
make_offer会返回 409 错误。
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-