Servers Playground How we check Add a server Log in

Buywhere Mcp

Working · 838 ms

io.github.BuyWhere/buywhere-mcpv1.2.0

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

Commerce

Source Website Registry entry

Maintain this server? Claim it

Try it

Call this server's tools from your browser. Nothing to install.

https://api.buywhere.ai/mcp

Authorization (required)

Bearer token. Free key at https://api.buywhere.ai/v1/auth/register (1,000 calls/day, no card).

Requests go through mcptry because browsers can't call most MCP servers directly. Header values are sent to the server for that request only and are never stored or logged.

Tool list from our last check. Connect live to refresh it.

compare_products

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

idsarray, required

Array of product IDs to compare (2-10)

This tool isn't marked read-only, so it may change something on the server or in an account you connected.

I understand, run it anyway

Buywhere Mcp MCP server | mcptry

Tools (13)

compare_products

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

Argument	Type	Description
ids*	array	Array of product IDs to compare (2-10)

Input schema (JSON)

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

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.

Argument	Type	Description
ids*	array	Array of product IDs to compare (2-10)
deliver_to*	string	REQUIRED. Buyer delivery country/market (ISO country code, e.g. "SG", "US").

Input schema (JSON)

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

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.

Argument	Type	Description
q	string	Keyword search query — alias for product_name
market	string	Alias for country_code (deprecated, use country_code).
region	string	Region filter - use "us" for United States or "sea" for Southeast Asia
country	string	Alias for country_code (deprecated, use country_code)
category	string	Category to filter by (e.g., "electronics", "fashion")
deliver_to	string	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.

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.

Argument	Type	Description
q	string	Keyword search query — alias for product_name
region	string	Region filter - use "us" for United States or "sea" for Southeast Asia
country	string	Alias for country_code (deprecated, use country_code)
category	string	Category to filter by (e.g., "electronics", "fashion")
deliver_to*	string	REQUIRED. Buyer delivery country/market (ISO country code, e.g. "SG", "US").
country_code	string	Country to search in (defaults to SG). Alias: country.
product_name	string	Product name to find best price for (e.g., "iphone 15 pro 256gb", "samsung galaxy s24")

Input schema (JSON)

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.

Argument	Type	Description
limit	integer	Number of similar products to return (1-10, default 10)
product_id*	string	UUID of the source product

Input schema (JSON)

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

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), 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"`.

Argument	Type	Description
limit	integer	Number of results (max 100, default 20)
market	string	Alias for country_code (deprecated, use country_code).
offset	integer	Pagination offset
region	string	Filter by region (sea, us, eu, au)
country	string	Alias for country_code (deprecated, use country_code)
category	string	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.

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

Argument	Type	Description
limit	integer	Number of results (max 100, default 20)
offset	integer	Pagination offset
region	string	Filter by region (sea, us, eu, au)
country	string	Alias for country_code (deprecated, use country_code)
category	string	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.
currency	string	Filter by currency code (SGD, USD, MYR, VND, THB). Defaults to SGD.
deliver_to*	string	REQUIRED. Buyer delivery country/market (ISO country code, e.g. "SG", "US").
country_code

get_product

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

Argument	Type	Description
id*	string	Product UUID

Input schema (JSON)

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

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.

Argument	Type	Description
id*	string	Product UUID
deliver_to*	string	REQUIRED. Buyer delivery country/market (ISO country code, e.g. "SG", "US").

Input schema (JSON)

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

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.

Argument	Type	Description
source*	string	Data source identifier (e.g. "shopee_sg", "amazon_sg", "lazada_sg")
products*	array	Array of product objects to ingest (max 1000)

Input schema (JSON)

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

list_categories

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

Argument	Type	Description
market	string	Alias for country_code (deprecated, use country_code).
region	string	Region alias mapped to ISO country code.
country	string	Alias for country_code (deprecated, use country_code)
country_code	string	Filter by ISO country code. Defaults to SG.

Input schema (JSON)

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

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.

Argument	Type	Description
q	string	Keyword search query
mode	string	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.
limit	integer	Number of results (max 100, default 20)
query	string	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.

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.

Argument	Type	Description
q	string	Keyword search query
mode	string	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.
limit	integer	Number of results (max 100, default 20)
query	string	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	string	Filter by merchant platform (e.g. lazada, shopee, amazon)
offset	integer	Pagination offset
region	string	Filter by region (sea, us, eu, au)

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

Input schema (JSON)

{
  "type": "object",
  "properties": {
    "q": {
      "type": "string",
      "description": "Keyword search query"
    },
    "mode": {
      "enum": [
        "keyword",
        "semantic",
        "hybrid"
      ],
      "type": "string",
      "default": "keyword",
      "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."
    },
    "limit": {
      "type": "integer",
      "default": 20,
      "description": "Number of results (max 100, default 20)"
    },
    "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)"
    },
    "market": {
      "type": "string",
      "description": "Alias for country_code (deprecated, use country_code)."
    },
    "offset": {
      "type": "integer",
      "default": 0,
      "description": "Pagination offset"
    },
    "region": {
      "type": "string",
      "description": "Filter by region (sea, us, eu, au)"
    },
    "compact": {
      "type": "boolean",
      "default": false,
      "description": "Return agent-optimized compact shape: structured_specs, comparison_attributes, normalized_price_usd. Reduces response size ~40%. Recommended for agent tool-use."
    },
    "country": {
      "type": "string",
      "description": "Alias for country_code (deprecated, use country_code)"
    },
    "category": {
      "type": "string",
      "description": "Filter by product category name (e.g. \"Laptops\", \"Smartphones\", \"Televisions\"). Use to exclude accessories and get actual products."
    },
    "max_price": {
      "type": "number",
      "description": "Maximum price (in currency inferred from country_code, or SGD by default)"
    },
    "min_price": {
      "type": "number",
      "description": "Minimum price (in currency inferred from country_code, or SGD by default)"
    },
    "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_code": {
      "enum": [
        "SG",
        "US",
        "VN",
        "TH",
        "MY"
      ],
      "type": "string",
      "description": "Filter by ISO country code. Also infers default currency for price filters (SG→SGD, US→USD, VN→VND, TH→THB, MY→MYR)."
    }
  }
}

Input schema (JSON)

{
  "type": "object",
  "required": [
    "deliver_to"
  ],
  "properties": {
    "q": {
      "type": "string",
      "description": "Keyword search query"
    },
    "mode": {
      "enum": [
        "keyword",
        "semantic",
        "hybrid"
      ],
      "type": "string",
      "default": "keyword",
      "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."
    },
    "limit": {
      "type": "integer",
      "default": 20,
      "description": "Number of results (max 100, default 20)"
    },
    "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)"
    },
    "offset": {
      "type": "integer",
      "default": 0,
      "description": "Pagination offset"
    },
    "region": {
      "type": "string",
      "description": "Filter by region (sea, us, eu, au)"
    },
    "compact": {
      "type": "boolean",
      "default": false,
      "description": "Return agent-optimized compact shape: structured_specs, comparison_attributes, normalized_price_usd. Reduces response size ~40%. Recommended for agent tool-use."
    },
    "country": {
      "type": "string",
      "description": "Alias for country_code (deprecated, use country_code)"
    },
    "category": {
      "type": "string",
      "description": "Filter by product category name (e.g. \"Laptops\", \"Smartphones\", \"Televisions\"). Use to exclude accessories and get actual products."
    },
    "max_price": {
      "type": "number",
      "description": "Maximum price (in currency inferred from country_code, or SGD by default)"
    },
    "min_price": {
      "type": "number",
      "description": "Minimum price (in currency inferred from country_code, or SGD by default)"
    },
    "deliver_to": {
      "type": "string",
      "description": "REQUIRED. Buyer delivery country/market (ISO country code, e.g. \"SG\", \"US\")."
    },
    "country_code": {
      "enum": [
        "SG",
        "US",
        "VN",
        "TH",
        "MY"
      ],
      "type": "string",
      "description": "Filter by ISO country code. Also infers default currency for price filters (SG→SGD, US→USD, VN→VND, TH→THB, MY→MYR)."
    }
  }
}