Content
# mercapi-mcp
Let your AI assistant search [Mercari](https://jp.mercari.com), Japan's largest second-hand marketplace, in plain language — no scraping, no manual filtering. An [MCP](https://modelcontextprotocol.io) server built on [mercapi](https://github.com/zhu-kai/mercapi-node).
Ask things like:
> "Find a used Daiwa Saltiga reel under ¥30,000 in good condition, cheapest first."
>
> "What's this seller's rating, and what else are they selling?"
>
> "Any auctions ending soon for vintage Game Boy games?"
The assistant calls the tools below, gets back compact results with direct `jp.mercari.com` links, and reasons over them for you.
## Setup
Requires Node ≥ 20.
**Claude Code**
```bash
claude mcp add mercari -- npx -y mercapi-mcp
```
**Claude Desktop / Cursor** — add to your `mcpServers` config:
```json
{
"mcpServers": {
"mercari": {
"command": "npx",
"args": ["-y", "mercapi-mcp"]
}
}
}
```
No API key or account needed.
## Tools
| Tool | Purpose |
|---|---|
| `search_items` | Search listings by keyword |
| `get_item` | Full detail for one listing |
| `get_seller` | A seller's profile and ratings |
| `get_seller_items` | Everything one seller has listed |
**`search_items`** is the workhorse. The assistant chooses:
- **Filters** — `priceMin`/`priceMax` (JPY), `condition` (`brand_new` → `bad`), `status` (`on_sale`/`sold`/`all`), `excludeKeyword`
- **Sorting** — `score` (default), `price_asc`, `price_desc`, `newest`, `likes`
- **How much to return** — `limit` (1–120, default 20) and `detail` (`compact` or `full`)
- **Output format** — `format` (`text`, default, or `json` for raw structured data)
- **Pagination** — pass `pageToken` from a previous result
All four tools accept `format: "json"` to return structured objects (mercapi's parsed fields) instead of human-readable text — useful for programmatic downstream use.
Auction listings are flagged with current bid count and deadline; `get_item` returns full auction state (starting price, highest bid, ends-at). Japanese keywords give the best results.
## How it works
Results come back as compact structured text rather than raw JSON — roughly 90% fewer tokens for the same information, so the assistant can scan many listings without blowing its context. Every item includes its `https://jp.mercari.com/item/{id}` link so you can open anything it finds.
## Notes
- **Unofficial API.** Requests hit Mercari's private endpoints from your own machine's IP. Fine for interactive use; heavy automated querying may get throttled.
- API health is monitored continuously upstream — [status page](https://zhu-kai.github.io/mercapi-node/).
- This is a read-only search tool. It cannot buy, bid, message, or list items.
## Credits
Wraps [mercapi](https://www.npmjs.com/package/mercapi) (Node), itself a port of [take-kun/mercapi](https://github.com/take-kun/mercapi) (Python), which reverse-engineered the Mercari API.
## License
MIT
