# BuyWhere/buywhere-mcp [Health: Active]

**Category:** 🛒 E-Commerce  
**Repository:** https://github.com/BuyWhere/buywhere-mcp  
**GitHub Stars:** 15  
**npm Downloads (last month):** 444  
**Views:** 4  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/buywhere-buywhere-mcp

## Description
Cross-border e-commerce product catalog for AI agents. Search 3M+ products across Singapore, SEA, and US markets with price comparison and deal discovery. Install via npx @buywhere/mcp-server.

## Tools
Capabilities this server exposes over MCP:

- **search_products** — Search the BuyWhere product catalog by keyword. Treat deliver_to as REQUIRED for buyer-facing use (ISO-3166 country of the end user); it takes precedence over country_code/country and prevents all-market scans. Returns product records with title, description, image, price, and merchant information. Covers e-commerce platforms across Singapore, Malaysia, Indonesia, Thailand, Vietnam, and US. Use compact=true for agent-optimized responses with structured_specs, comparison_attributes, and normalized_price_usd fields. BUY-74597 degraded contract: when the catalog query cannot complete inside the user-facing timeout, this tool returns a 200-OK envelope with `meta.status="degraded"`, `meta.emptiness_reason="api_error"` with `meta.degraded_kind="timeout"` (or `"partial_timeout"` / `"auth_failure"`), `meta.confidence="low"`, and `meta.diagnostic.timed_out_stage` naming the failed stage (catalog_search / offer_aggregation / merchant_join). It never returns an unqualified empty result when the cause is timeout, auth failure, upstream exception, or circuit breaker. Agents should branch on `meta.degraded === true` (or `meta.status === "degraded"`) instead of treating empty `data` as no_match.
- **get_product** — Get a specific product by its ID, including full details and current price.
- **compare_products** — Compare multiple products side-by-side. Returns price, brand, rating, and category for each.
- **get_deals** — Get discounted products sorted by discount percentage. Returns schema.org/Product entities with schema.org/Offer properties: price, priceCurrency, availability, originalPrice, and discountPercentage. Covers Singapore, Malaysia, Indonesia, Thailand, Vietnam, and US e-commerce. Supports currency, region (sea, us, eu, au) and country (SG, US, VN, MY, ...) filters. BUY-74597 degraded contract: when the discount-index scan cannot complete inside the user-facing timeout, this tool returns a 200-OK envelope with `meta.status="degraded"`, `meta.emptiness_reason="api_error"` with `meta.degraded_kind="timeout"` (or `"partial_timeout"` / `"auth_failure"`), `meta.confidence="low"`, and `meta.diagnostic.timed_out_stage` (typically `offer_aggregation`). It never returns an unqualified empty result when the cause is timeout, auth failure, upstream exception, or circuit breaker. Branch on `meta.degraded === true` or `meta.status === "degraded"`.
- **list_categories** — List top-level product categories available in the BuyWhere catalog.
- **find_best_price** — Use this whenever a user asks about prices, wants to find the cheapest option, or asks "what's the best price for X" or "where can I buy X for the lowest price". Returns schema.org/Product entities with schema.org/AggregateOffer (lowPrice, offerCount, priceCurrency) across all merchants. BUY-74597 degraded contract: when the candidates query cannot complete inside the user-facing timeout, this tool returns a 200-OK envelope with `meta.degraded=true`, `meta.status="degraded"`, `meta.emptiness_reason="api_error"` with `meta.degraded_kind="timeout"` (or `"partial_timeout"` / `"auth_failure"`), `meta.confidence="low"`, and `meta.diagnostic.timed_out_stage="catalog_search"`, with `best_price=null` and `alternatives=[]`. It never returns an unqualified empty result when the cause is timeout, auth failure, upstream exception, or circuit breaker.
- **find_similar** — Find products similar to a given product using vector similarity. Returns up to 10 nearest neighbours by semantic meaning (title+description embedding). Useful for "more like this" recommendations.
- **ingest_products** — Ingest (upsert) a batch of products into the BuyWhere catalog. Use this to add or update product listings from any merchant/source. Requires a valid API key with ingest permissions. Accepts up to 1000 products per call with source, SKU, title, price, URL, and optional metadata.
- **search_products_v2** — REQUIRED deliver_to. Search the BuyWhere product catalog by keyword. The deliver_to parameter is REQUIRED (ISO country code, e.g. "SG", "US") — it takes precedence over country_code/country and prevents all-market scans. Always pass deliver_to="SG" (or your buyer's country). Returns product records with title, description, image, price, and merchant information. Covers e-commerce platforms across Singapore, Malaysia, Indonesia, Thailand, Vietnam, and US. Use compact=true for agent-optimized responses with structured_specs, comparison_attributes, and normalized_price_usd fields.
- **get_product_v2** — REQUIRED deliver_to. Get a specific product by its ID, including full details and current price. Always pass deliver_to="SG" (or your buyer's country). Response includes a resolved outbound_url (https://…) that routes the buyer through the BuyWhere click tracker when the product has merchant offers.
- **compare_products_v2** — REQUIRED deliver_to. Compare multiple products side-by-side. Always pass deliver_to="SG" (or your buyer's country). Returns price, brand, rating, category, and a resolved outbound_url per product for the buyer market.
- **get_deals_v2** — REQUIRED deliver_to. Get discounted products sorted by discount percentage. Always pass deliver_to="SG" (or your buyer's country). Returns schema.org/Product entities with schema.org/Offer properties: price, priceCurrency, availability, originalPrice, and discountPercentage. Covers Singapore, Malaysia, Indonesia, Thailand, Vietnam, and US e-commerce. Supports currency, region (sea, us, eu, au) and country (SG, US, VN, MY, ...) filters.
- **find_best_price_v2** — REQUIRED deliver_to. Use this whenever a user asks about prices, wants to find the cheapest option, or asks "what's the best price for X" or "where can I buy X for the lowest price". Always pass deliver_to="SG" (or your buyer's country). Returns schema.org/Product entities with schema.org/AggregateOffer (lowPrice, offerCount, priceCurrency) across all merchants. Response includes a shopping_job_id (UUID) you can use to resume a multi-merchant price-comparison session for the buyer.

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `npx` (confidence: high):

```json
"mcpServers": {
  "buywhere-mcp": {
    "command": "npx",
    "args": ["-y","@buywhere/mcp-server"],
    "env": {
      "BUYWHERE_API_KEY": ""
    }
  }
}
```

**Requires environment variables:** `BUYWHERE_API_KEY` — the values above are empty placeholders; fill in real credentials before running (see the repository for what each one is for).

## Documentation

## What BuyWhere/buywhere-mcp does

BuyWhere/buywhere-mcp MCP server exposes product catalog and price-comparison operations to MCP-compatible AI clients. The catalog contains more than 3 million products and covers Singapore, the United States, Malaysia, Thailand, and Vietnam markets according to the project material. Agents can search by keyword, category, price range, and country, then retrieve structured information such as prices, specifications, and images.

The server is intended for agent commerce workflows, including product recommendations, cross-border research, comparison shopping, and deal discovery. It is described as a product search API rather than a system for managing an online store.

## How it works

The package runs as an MCP server and communicates with clients through the standard MCP interface. A local installation uses the npm package with an API key supplied through the environment. The project also documents a remote endpoint at `https://api.buywhere.ai/mcp`, using JSON-RPC 2.0 and protocol version `2024-11-05`.

BuyWhere/buywhere-mcp can be connected to Claude Desktop, Cursor, Cline, Windsurf, and other MCP-compatible clients listed by the project.

## Setup and configuration

Install the local server with Node.js and npm:

```bash
export BUYWHERE_API_KEY=bw_live_xxxx
npx -y @buywhere/mcp-server
```

An API key can be obtained through the BuyWhere API-key page or by registering with the documented `POST https://api.buywhere.ai/v1/auth/register` request. Configure the same command and environment variable in the MCP settings for the client you use. The example configurations use `npx -y @buywhere/mcp-server`, which avoids an interactive npm confirmation prompt.

The BuyWhere/buywhere-mcp MCP server can also be used through the hosted MCP endpoint instead of running the npm package locally.

## Tools and capabilities

The server documents these operations:

- Search products by keyword, category, price, or country.
- Fetch product details by ID, including prices, specifications, and images.
- Compare between two and ten products side by side.
- Find the lowest-priced deliverable listing across merchants.
- Find products with significant price drops.
- List the available product-category taxonomy.
- Find similar products using vector similarity.
- Submit product URLs for catalog ingestion.

Version 2 tools add delivery-aware behavior. `search_products_v2`, `get_deals_v2`, and `find_best_price_v2` require a `deliver_to` ISO country value; `compare_products_v2` accepts it optionally, and `get_product_v2` retrieves product details by ID.

## Limitations and notes

Requests require a BuyWhere API key for the local package. Product prices, merchant listings, and delivery results may depend on the selected market and, for v2 operations, the destination country. The repository is licensed under MIT.

_Full upstream README: https://allmcps.com/mcp/buywhere-buywhere-mcp/readme_