Mercari JP Search + Yahoo Auctions + eBay GUI

A Python application to search Mercari Japan, Yahoo Auctions, and eBay products with a Web GUI. Supports simple, bulk, and combined cross-platform searches with powerful filtering options.

Features

• Mercari Simple Search — Single keyword with price range, exclude keywords, status/condition filters

• Mercari Bulk Search — Upload a .txt, .csv, or .xlsx file (or paste keywords) and search multiple Mercari keywords at once

• Yahoo Auctions Simple Search — Search Yahoo Auctions with price range, status (live/sold), condition, sort, and BIN-only filters

• Yahoo Auctions Bulk Search — Multi-keyword Yahoo Auctions search with CSV export

• Combined Mercari + Yahoo Bulk Search — Search both platforms simultaneously with per-keyword results shown side-by-side

• eBay Simple Search — Search eBay with keyword, price, condition, sort, and site (US/UK/DE/JP/etc.)

• eBay Bulk Search — Multi-keyword eBay search with CSV export

• Filters — Price range, item status, condition, seller review count (Mercari bulk), sort order, BIN-only (Yahoo/eBay)

• Shop Item Detection — Automatically detects /shops/product/ vs /item/ URLs

• Description Viewer — View item descriptions with auto-translate from Japanese to English

• CSV Export — Download search results as CSV for all search types

• Japanese Translation — Product names and descriptions automatically translated to English

Related MCP server: mercadolibre-mcp

Requirements

• Python 3.11+

• Dependencies listed in pyproject.toml

Setup

1. Clone the repository:

   git clone https://github.com/rafayqazi/mercari-jp-mcp.git
   cd mercari-jp-mcp

2. Create and activate a virtual environment:

   uv venv
   source .venv/bin/activate  # Windows: .venv\Scripts\activate
   uv pip install -e .

Usage

Web GUI (Flask Application — Recommended)

Run the built-in Flask web server:

uv run mercari_gui.py

Then open http://127.0.0.1:5000 in your browser.

Windows users can also double-click start_gui.bat to launch directly.

The GUI has seven tabs:

• Simple Search — Single keyword with price range, exclude keywords, status/condition filters

• Mercari Bulk Search — Paste multiple keywords (one per line) or upload a .txt / .csv / .xlsx file. Filter by status, condition, and seller review count (min/max). Results are grouped by keyword and can be exported as CSV.

• Yahoo Auctions — Single keyword search on Yahoo Auctions with price range, status (live/sold), condition, sort order, and BIN-only filter

• Yahoo Bulk — Multi-keyword Yahoo Auctions search with file upload support and CSV export

• Mercari + Yahoo Bulk — Search both platforms at once. Results are displayed side-by-side per keyword with Mercari on the left and Yahoo on the right.

• eBay Search — Search eBay by keyword with price range, condition, sort, and site selection (US/UK/Japan/etc.). Requires an eBay App ID.

• eBay Bulk — Multi-keyword eBay search with file upload and CSV export.

Click Description (Mercari) or Detail (Yahoo) on any result to view item details with auto-translate from Japanese to English. Click View to open the item on the respective platform.

eBay Setup

To use the eBay search features, you need an eBay Developer Account and an App ID (Client ID):

1. Go to developer.ebay.com

2. Create an application and get your App ID (Client ID)

3. Paste the App ID in the settings bar at the top of the GUI and click Save

4. The App ID is stored in your browser's localStorage for future sessions

Alternatively, set the EBAY_APP_ID environment variable.

MCP Server (for Claude Desktop)

The MCP server exposes a search_mercari_jp tool that returns formatted markdown results:

uv run server.py

Configure in claude_desktop_config.json:

{
  "mcpServers": {
    "mercari": {
      "command": "uv",
      "args": [
        "--directory",
        "C:\\PATH\\TO\\mercari-jp-mcp",
        "run",
        "server.py"
      ]
    }
  }
}

The server automatically limits API pagination (max_items) for faster responses and returns results as markdown with images and links.

Available MCP tools:

• search_mercari_jp — Search Mercari Japan items with keyword, price, and exclusion filters

• search_ebay — Search eBay items with keyword, price, condition, sort, and site filters. Requires app_id parameter or EBAY_APP_ID environment variable.

Security

• No API keys, tokens, or credentials are stored in this repository

• All search requests go directly to Mercari Japan's public API

• The .gitignore excludes virtual environments, cache files, and local config

• Environment files (.env, .env.*) are excluded — never commit secrets

How It Works

The app uses the mercari library (MIT license) to interface with Mercari Japan's public API. Search results are parsed, filtered, and optionally translated via Google Translate API.

Acknowledgments

• marvinody/mercari — Mercari API client

• jlowin/fastmcp — MCP framework