buywhere-mcp

Agent-native product catalog: 300M+ products, 150,000+ stores, deliver_to ranking.

Should I use this

Description quality

93%

Schema completeness

97%

Naming quality

95%

Poisoning risk

100%

Permission match

100%

Protocol compliance

100%

Findings (1)

LOWTool 'compare_products' description lacks action verbin compare_products

Based on automated analysis of tool definitions and protocol compliance.

Context Cost

~4,241Tokens (tool definitions)

~2.7 KBTypical response size

Significant attention impact (3.31% of 128k context)

This is the approximate number of tokens consumed each time the server's tools are loaded into a model's context. Higher counts reduce the attention available for other tasks.

Install

One-Click Install

Add this to your `claude_desktop_config.json` file:

{
  "mcpServers": {
    "buywhere-mcp": {
      "command": "npx",
      "args": [
        "@buywhere/mcp-server"
      ]
    }
  }
}

Runnable packages

npm@buywhere/mcp-server0.3.17stdio

Remote endpoints

https://api.buywhere.ai/mcpstreamable-http

What it can do

Tool inventory

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.

Input Schema

{
  "type": "object",
  "properties": {
    "q": {
      "type": "string",
      "description": "Keyword search query"
    },
    "query": {
      "type": "string",
      "description": "Alias for q (accepted for agent convenience; use q). Without this, callers passing `query` get 0 rows and the reltuples-derived total — see BUY-75287."
    },
    "domain": {
      "type": "string",
      "description": "Filter by merchant platform (e.g. lazada, shopee, amazon)"
    },
    "region": {
      "type": "string",
      "description": "Filter by region (sea, us, eu, au)"
    },
    "country_code": {
      "type": "string",
      "enum": [
        "SG",
        "US",
        "VN",
        "TH",
        "MY"
      ],
      "description": "Filter by ISO country code. Also infers default currency for price filters (SG→SGD, US→USD, VN→VND, TH→THB, MY→MYR)."
    },
    "deliver_to": {
      "type": "string",
      "description": "Treat as REQUIRED for buyer-facing use: ISO-3166 country of the END USER (e.g. \"SG\", \"US\"). Without it results are not shipping-ranked and may be undeliverable. Preferred over country_code/country."
    },
    "country": {
      "type": "string",
      "description": "Alias for country_code (deprecated, use country_code)"
    },
    "market": {
      "type": "string",
      "description": "Alias for country_code (deprecated, use country_code)."
    },
    "min_price": {
      "type": "number",
      "description": "Minimum price (in currency inferred from country_code, or SGD by default)"
    },
    "max_price": {
      "type": "number",
      "description": "Maximum price (in currency inferred from country_code, or SGD by default)"
    },
    "limit": {
      "type": "integer",
      "description": "Number of results (max 100, default 20)",
      "default": 20
    },
    "offset": {
      "type": "integer",
      "description": "Pagination offset",
      "default": 0
    },
    "compact": {
      "type": "boolean",
      "description": "Return agent-optimized compact shape: structured_specs, comparison_attributes, normalized_price_usd. Reduces response size ~40%. Recommended for agent tool-use.",
      "default": false
    },
    "category": {
      "type": "string",
      "description": "Filter by product category name (e.g. \"Laptops\", \"Smartphones\", \"Televisions\"). Use to exclude accessories and get actual products."
    },
    "mode": {
      "type": "string",
      "enum": [
        "keyword",
        "semantic",
        "hybrid"
      ],
      "description": "Search mode: keyword=FTS only (default, matches REST /v1/products/search), semantic=vector only, hybrid=RRF blend of FTS+vector. Falls back to keyword if vector DB or FLOWAI_EMBED_API_KEY unavailable.",
      "default": "keyword"
    }
  }
}

Get a specific product by its ID, including full details and current price.

Input Schema

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "Product UUID"
    }
  },
  "required": [
    "id"
  ]
}

Compare multiple products side-by-side. Returns price, brand, rating, and category for each.

Input Schema

{
  "type": "object",
  "properties": {
    "ids": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Array of product IDs to compare (2-10)",
      "minItems": 2,
      "maxItems": 10
    }
  },
  "required": [
    "ids"
  ]
}

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), country (SG, US, VN, MY, ...) and category 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"`.

Input Schema

{
  "type": "object",
  "properties": {
    "min_discount": {
      "type": "number",
      "description": "Minimum discount percentage (default 10)",
      "default": 10
    },
    "currency": {
      "type": "string",
      "description": "Filter by currency code (SGD, USD, MYR, VND, THB). Defaults to SGD.",
      "default": "SGD"
    },
    "region": {
      "type": "string",
      "description": "Filter by region (sea, us, eu, au)"
    },
    "country_code": {
      "type": "string",
      "enum": [
        "SG",
        "US",
        "VN",
        "TH",
        "MY"
      ],
      "description": "Filter by ISO country code. Alias: country."
    },
    "deliver_to": {
      "type": "string",
      "description": "Treat as REQUIRED for buyer-facing use: ISO-3166 country of the END USER (e.g. \"SG\", \"US\"). Without it results are not shipping-ranked and may be undeliverable. Preferred over country_code/country."
    },
    "country": {
      "type": "string",
      "description": "Alias for country_code (deprecated, use country_code)"
    },
    "market": {
      "type": "string",
      "description": "Alias for country_code (deprecated, use country_code)."
    },
    "category": {
      "type": "string",
      "description": "Filter deals by product category (e.g. \"Electronics\", \"Beauty\", \"home_and_kitchen\"). Handler matches against category text and category_path[1]; slug-style input is accepted. BUY-76853/BUY-83657."
    },
    "limit": {
      "type": "integer",
      "description": "Number of results (max 100, default 20)",
      "default": 20
    },
    "offset": {
      "type": "integer",
      "description": "Pagination offset",
      "default": 0
    }
  }
}

List top-level product categories available in the BuyWhere catalog.

Input Schema

{
  "type": "object",
  "properties": {
    "region": {
      "type": "string",
      "enum": [
        "us",
        "sg",
        "my",
        "gb",
        "in",
        "au"
      ],
      "description": "Region alias mapped to ISO country code."
    },
    "country_code": {
      "type": "string",
      "enum": [
        "SG",
        "US",
        "VN",
        "TH",
        "MY",
        "GB",
        "IN",
        "AU"
      ],
      "description": "Filter by ISO country code. Defaults to SG."
    },
    "country": {
      "type": "string",
      "description": "Alias for country_code (deprecated, use country_code)"
    },
    "market": {
      "type": "string",
      "description": "Alias for country_code (deprecated, use country_code)."
    }
  }
}

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.

Input Schema

{
  "type": "object",
  "properties": {
    "q": {
      "type": "string",
      "description": "Keyword search query — alias for product_name"
    },
    "product_name": {
      "type": "string",
      "description": "Product name to find best price for (e.g., \"iphone 15 pro 256gb\", \"samsung galaxy s24\")"
    },
    "category": {
      "type": "string",
      "description": "Category to filter by (e.g., \"electronics\", \"fashion\")"
    },
    "country_code": {
      "type": "string",
      "enum": [
        "SG",
        "MY",
        "TH",
        "PH",
        "VN",
        "ID",
        "US"
      ],
      "description": "Country to search in (defaults to SG). Alias: country."
    },
    "deliver_to": {
      "type": "string",
      "description": "Treat as REQUIRED for buyer-facing use: ISO-3166 country of the END USER (e.g. \"SG\", \"US\"). Without it results are not shipping-ranked and may be undeliverable. Preferred over country_code/country."
    },
    "country": {
      "type": "string",
      "description": "Alias for country_code (deprecated, use country_code)"
    },
    "market": {
      "type": "string",
      "description": "Alias for country_code (deprecated, use country_code)."
    },
    "region": {
      "type": "string",
      "enum": [
        "us",
        "sea"
      ],
      "description": "Region filter - use \"us\" for United States or \"sea\" for Southeast Asia"
    }
  }
}

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.

Input Schema

{
  "type": "object",
  "properties": {
    "product_id": {
      "type": "string",
      "description": "UUID of the source product"
    },
    "limit": {
      "type": "integer",
      "description": "Number of similar products to return (1-10, default 10)",
      "default": 10
    }
  },
  "required": [
    "product_id"
  ]
}

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.

Input Schema

{
  "type": "object",
  "properties": {
    "source": {
      "type": "string",
      "description": "Data source identifier (e.g. \"shopee_sg\", \"amazon_sg\", \"lazada_sg\")"
    },
    "products": {
      "type": "array",
      "description": "Array of product objects to ingest (max 1000)",
      "items": {
        "type": "object",
        "required": [
          "sku",
          "merchant_id",
          "title",
          "price",
          "url"
        ],
        "properties": {
          "sku": {
            "type": "string",
            "description": "Unique stock keeping unit identifier"
          },
          "merchant_id": {
            "type": "string",
            "description": "Merchant identifier"
          },
          "title": {
            "type": "string",
            "description": "Product title"
          },
          "description": {
            "type": "string",
            "description": "Product description"
          },
          "price": {
            "type": "number",
            "description": "Current price (must be >= 0)"
          },
          "currency": {
            "type": "string",
            "description": "Currency code (default: SGD)",
            "default": "SGD"
          },
          "url": {
            "type": "string",
            "description": "Product URL on the merchant site"
          },
          "image_url": {
            "type": "string",
            "description": "Main product image URL"
          },
          "category": {
            "type": "string",
            "description": "Product category"
          },
          "brand": {
            "type": "string",
            "description": "Brand name"
          },
          "is_active": {
            "type": "boolean",
            "description": "Whether the product is active (default: true)"
          },
          "is_available": {
            "type": "boolean",
            "description": "Whether the product is in stock"
          },
          "country_code": {
            "type": "string",
            "description": "ISO country code (e.g. \"SG\", \"US\")"
          },
          "region": {
            "type": "string",
            "description": "Region identifier (e.g. \"sea\", \"us\")"
          },
          "metadata": {
            "type": "object",
            "description": "Additional product metadata"
          }
        }
      }
    }
  },
  "required": [
    "source",
    "products"
  ]
}

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.

Input Schema

{
  "type": "object",
  "properties": {
    "q": {
      "type": "string",
      "description": "Keyword search query"
    },
    "query": {
      "type": "string",
      "description": "Alias for q (accepted for agent convenience; use q). Without this, callers passing `query` get 0 rows and the reltuples-derived total — see BUY-75287."
    },
    "domain": {
      "type": "string",
      "description": "Filter by merchant platform (e.g. lazada, shopee, amazon)"
    },
    "region": {
      "type": "string",
      "description": "Filter by region (sea, us, eu, au)"
    },
    "country_code": {
      "type": "string",
      "enum": [
        "SG",
        "US",
        "VN",
        "TH",
        "MY"
      ],
      "description": "Filter by ISO country code. Also infers default currency for price filters (SG→SGD, US→USD, VN→VND, TH→THB, MY→MYR)."
    },
    "deliver_to": {
      "type": "string",
      "description": "REQUIRED. Buyer delivery country/market (ISO country code, e.g. \"SG\", \"US\")."
    },
    "country": {
      "type": "string",
      "description": "Alias for country_code (deprecated, use country_code)"
    },
    "min_price": {
      "type": "number",
      "description": "Minimum price (in currency inferred from country_code, or SGD by default)"
    },
    "max_price": {
      "type": "number",
      "description": "Maximum price (in currency inferred from country_code, or SGD by default)"
    },
    "limit": {
      "type": "integer",
      "description": "Number of results (max 100, default 20)",
      "default": 20
    },
    "offset": {
      "type": "integer",
      "description": "Pagination offset",
      "default": 0
    },
    "compact": {
      "type": "boolean",
      "description": "Return agent-optimized compact shape: structured_specs, comparison_attributes, normalized_price_usd. Reduces response size ~40%. Recommended for agent tool-use.",
      "default": false
    },
    "category": {
      "type": "string",
      "description": "Filter by product category name (e.g. \"Laptops\", \"Smartphones\", \"Televisions\"). Use to exclude accessories and get actual products."
    },
    "mode": {
      "type": "string",
      "enum": [
        "keyword",
        "semantic",
        "hybrid"
      ],
      "description": "Search mode: keyword=FTS only (default, matches REST /v1/products/search), semantic=vector only, hybrid=RRF blend of FTS+vector. Falls back to keyword if vector DB or FLOWAI_EMBED_API_KEY unavailable.",
      "default": "keyword"
    }
  },
  "required": [
    "deliver_to"
  ]
}

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.

Input Schema

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "Product UUID"
    },
    "deliver_to": {
      "type": "string",
      "description": "REQUIRED. Buyer delivery country/market (ISO country code, e.g. \"SG\", \"US\")."
    }
  },
  "required": [
    "id",
    "deliver_to"
  ]
}

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.

Input Schema

{
  "type": "object",
  "properties": {
    "ids": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Array of product IDs to compare (2-10)",
      "minItems": 2,
      "maxItems": 10
    },
    "deliver_to": {
      "type": "string",
      "description": "REQUIRED. Buyer delivery country/market (ISO country code, e.g. \"SG\", \"US\")."
    }
  },
  "required": [
    "ids",
    "deliver_to"
  ]
}

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), country (SG, US, VN, MY, ...) and category filters.

Input Schema

{
  "type": "object",
  "properties": {
    "min_discount": {
      "type": "number",
      "description": "Minimum discount percentage (default 10)",
      "default": 10
    },
    "currency": {
      "type": "string",
      "description": "Filter by currency code (SGD, USD, MYR, VND, THB). Defaults to SGD.",
      "default": "SGD"
    },
    "region": {
      "type": "string",
      "description": "Filter by region (sea, us, eu, au)"
    },
    "country_code": {
      "type": "string",
      "enum": [
        "SG",
        "US",
        "VN",
        "TH",
        "MY"
      ],
      "description": "Filter by ISO country code. Alias: country."
    },
    "deliver_to": {
      "type": "string",
      "description": "REQUIRED. Buyer delivery country/market (ISO country code, e.g. \"SG\", \"US\")."
    },
    "country": {
      "type": "string",
      "description": "Alias for country_code (deprecated, use country_code)"
    },
    "category": {
      "type": "string",
      "description": "Filter deals by product category (e.g. \"Electronics\", \"Beauty\", \"home_and_kitchen\"). Handler matches against category text and category_path[1]; slug-style input is accepted. BUY-76853/BUY-83657."
    },
    "limit": {
      "type": "integer",
      "description": "Number of results (max 100, default 20)",
      "default": 20
    },
    "offset": {
      "type": "integer",
      "description": "Pagination offset",
      "default": 0
    }
  },
  "required": [
    "deliver_to"
  ]
}

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.

Input Schema

{
  "type": "object",
  "properties": {
    "q": {
      "type": "string",
      "description": "Keyword search query — alias for product_name"
    },
    "product_name": {
      "type": "string",
      "description": "Product name to find best price for (e.g., \"iphone 15 pro 256gb\", \"samsung galaxy s24\")"
    },
    "category": {
      "type": "string",
      "description": "Category to filter by (e.g., \"electronics\", \"fashion\")"
    },
    "country_code": {
      "type": "string",
      "enum": [
        "SG",
        "MY",
        "TH",
        "PH",
        "VN",
        "ID",
        "US"
      ],
      "description": "Country to search in (defaults to SG). Alias: country."
    },
    "deliver_to": {
      "type": "string",
      "description": "REQUIRED. Buyer delivery country/market (ISO country code, e.g. \"SG\", \"US\")."
    },
    "country": {
      "type": "string",
      "description": "Alias for country_code (deprecated, use country_code)"
    },
    "region": {
      "type": "string",
      "enum": [
        "us",
        "sea"
      ],
      "description": "Region filter - use \"us\" for United States or \"sea\" for Southeast Asia"
    }
  },
  "required": [
    "deliver_to"
  ]
}

Community

Rate this Server

Evidence

Recent observations

Nov 2, 2026, 8:04 PM UTCverifiedversion not recorded13 tools

Oct 24, 2026, 5:32 PM UTCverifiedversion not recorded13 tools

Oct 16, 2026, 10:03 AM UTCverifiedversion not recorded13 tools

Oct 8, 2026, 6:33 PM UTCverifiedversion not recorded13 tools

Sep 30, 2026, 9:34 AM UTCverifiedversion not recorded13 tools

Sep 24, 2026, 7:32 AM UTCverifiedversion not recorded13 tools

Sep 17, 2026, 5:14 PM UTCverifiedversion not recorded13 tools

buywhere-mcp

Quality & Safety

Findings (1)

Context Cost

One-Click Install

Runnable packages

Remote endpoints

Tool inventory

Tools (13)

Input Schema

Input Schema

Input Schema

Input Schema

Input Schema

Input Schema

Input Schema

Input Schema

Input Schema

Input Schema

Input Schema

Input Schema

Input Schema

Rate this Server

Recent observations