Mercari

This MCP server provides programmable access to Mercari product search and details, letting you perform keyword searches, filter by price and category, and retrieve item details through a consistent, scriptable interface.

How to use

You can run the Mercari MCP server locally in two modes: a standard input/output (stdio) mode for direct integration and a Server-Sent Events (SSE) mode for streaming interactions over HTTP. In stdio mode, you start the server and interact with it through a local process. In SSE mode, you connect to a live HTTP endpoint to issue tool calls and receive results in real time. Once running, you can use the available tools to search Mercari items, fetch item details, and search by category with optional filters such as price ranges and item condition.

Tool interactions in SSE mode are exposed through endpoints that include a server URL, a dedicated SSE stream, a list of available tools, and a health check. The server is available at http://127.0.0.1:8000 with the SSE stream at http://127.0.0.1:8000/sse. Use the tools endpoint to discover available tools and call a specific tool to execute a Mercari search or fetch item details.

How to install

Prerequisites: Python 3.8 or newer, and a Python package manager (pip). Ensure you have a development environment ready to run Python applications.

Follow these steps to set up locally and run the MCP server.

1. Clone the project repository

2. Create and activate a virtual environment

3. Install the package in editable mode

Configuration and usage notes

Standard configuration for stdio mode and SSE mode is provided below. Use stdio mode if you prefer embedding the server as a local process, or use SSE mode to interact over HTTP with streaming capabilities.

# stdio mode (local server)
python -m mercari_mcp.server

# SSE mode (local HTTP server)
python scripts/run_sse_server.py
# or specify host/port
python scripts/run_sse_server.py --host 127.0.0.1 --port 8000

Tools and usage overview

The server exposes the following tools in SSE mode: search_mercari_items for keyword-based searches, get_mercari_item_detail for item details, and search_mercari_by_category for category-based searches. You can apply optional filters such as category, price range, item condition, sorting, and pagination to tailor results.

Available tools

search_mercari_items

Search Mercari items using keywords, optional category, brand, price range, condition, sort, order, and pagination.

get_mercari_item_detail

Retrieve detailed information for a specific Mercari item by its item_id.

search_mercari_by_category

Search Mercari items within a specific category with optional price range, condition, sort, and pagination.