Wallapop MCP Server

为 Wallapop 市场构建的混合型非官方 MCP 服务器，使用 TypeScript 编写。

• HTTP 主通道：对私有 api.wallapop.com v3 端点进行逆向工程调用

• SSR 回退：抓取 es.wallapop.com 页面中的 __NEXT_DATA__（商品详情、卖家资料）

• Playwright 回退：最后手段是使用屏幕外的有头浏览器（Wallapop 的 CDN 会阻止无头 Chrome）

• 身份验证：可选邮箱/密码或浏览器 Cookie 导入，用于收藏、已保存搜索、聊天和出价（令牌刷新 + 会话持久化）

非官方且与 Wallapop 无关联。使用 Wallapop 未记录的 API，该 API 可能随时更改或阻止流量——请自行承担使用风险，保持较低的请求量，并遵守其服务条款。

工具

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）

注意：对于启用 MFA 或 Keycloak 流程的账户，WALLAPOP_EMAIL/WALLAPOP_PASSWORD 可能会失败——在这种情况下，请从已登录的浏览器中将 Cookie 导出到 WALLAPOP_COOKIES_FILE（一个 Cookie 对象的 JSON 数组），服务器将直接使用它们。

工作原理

搜索（两步 API 流程）

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

2. GET /api/v3/search/section（每页 40 条）→ meta.next_page JWT；服务器将 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）。

回退链

1. API 请求，使用类似浏览器的请求头、UA 轮换、429 时指数退避，以及 403 时 X-Signature 重试

2. SSR HTML 抓取（es.wallapop.com/item/...、/user/...）——为卖家提供更丰富的数据（评分、计数）

3. 通过 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 错误。