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 はいつでも変更されたり、トラフィックをブロックしたりする可能性があります。自己責任で使用し、リクエスト量を抑え、Wallapop の利用規約を尊重してください。

ツール

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 を参照）

注: WALLAPOP_EMAIL/WALLAPOP_PASSWORD は、MFA または Keycloak フローを使用するアカウントでは失敗する可能性があります。その場合は、ログイン済みブラウザから WALLAPOP_COOKIES_FILE に Cookie をエクスポート（Cookie オブジェクトの JSON 配列）すると、サーバーはそれらを直接使用します。

仕組み

検索（2 段階 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）にも届きます。両方ともエンドツーエンドで検証済みです。

• オファーはクライアント生成のオファー ID を使用して POST /api/v3/delivery/buyer/offers で作成され、出品者は会話内でそれを受け取ります。

認証

• POST /api/v3/access/login を試行し、アクセス/リフレッシュトークン + Cookie をセッションファイルに保存します。JWT の有効期限が近づくと POST /api/v3/access/refresh で更新します。

• 自動ブラウザログインにフォールバックします。MFA チャレンジは検出され、エラーとして表示されます（手動で完了させ、その後 WALLAPOP_COOKIES_FILE に Cookie をエクスポートしてください）。

フォールバックチェーン

1. ブラウザ風ヘッダー、UA ローテーション、429 での指数バックオフ、403 での X-Signature リトライを使用した API リクエスト

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 エラーを返します。