Buywhere Mcp

io.github.BuyWherePublished by GitHub account BuyWherev1.2.0Updated Oct 24, 2026

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

VerifiedStreamable HTTPWeb executableWeb Search & ScrapingBusiness & Commerce

Overview

AI-generated overview

BuyWhere lets an assistant search a multi-market product catalog, compare prices across merchants and find deals, mainly for Singapore, US and Southeast Asian e

What you can do
Search the product catalog by keyword, category and price, with a required deliver_to country for buyer-facing results, and list the category taxonomy. Retrieve a single product's full details and current price, and compare several products side by side on price, brand, rating and category. Find the cheapest deliverable offer across merchants and surface discounted products sorted by discount percentage. Find similar products by vector similarity for recommendations. Ingest or upsert batches of product listings, which requires an API key with ingest permissions.
When to use it
Useful when building shopping or price-comparison agents that need live product data, deals and merchant offers for Singapore, US, Malaysia, Thailand or Vietnam markets, or when an assistant should answer questions like where to buy something at the lowest price.
Requirements
A BuyWhere API key, supplied as the BUYWHERE_API_KEY environment variable for the local npm package or as an Authorization bearer token for the remote endpoint. A key can be obtained from the registration endpoint without signup. The local package runs via npx and needs Node.js; the remote endpoint needs network access.
Before you install
The API key is a secret and should be kept out of shared configs and logs. The ingest_products tool writes to the catalog and needs a key with ingest permissions, so restrict it to trusted use. Product results include outbound links routed through a click tracker, and queries and country data are sent to BuyWhere's servers.

Installation

In SourceWeft

  1. Open Buywhere Mcp in the dashboard and add it to a workspace.
  2. Connect Authorization token credentials. They are stored privately and never shown on public pages.
  3. Enable the server for the chats that should use its tools.

Web executable via Streamable HTTP. Remote servers run from the web runtime once configured in a workspace.

Use with an agent

Paste this prompt into Claude Code, Codex, Cursor or another agent — or into SourceWeft chat. The agent reads this server's install guide, shows you its publisher, endpoint and sign-in, and adds it to your client once you agree. Keys never go into a command.

Read https://sourceweft.com/mcp/io.github.BuyWhere%2Fbuywhere-mcp/install.md and connect the MCP server it describes to my client. Before changing any config, show me its publisher, endpoint and sign-in method and wait for my OK. Never put an API key in a command or in a file I would commit; ask me where it should come from.

Read the install guide the agent follows

Other MCP clients

Add this to your client's mcpServers config.

{
  "mcpServers": {
    "buywhere": {
      "type": "http",
      "url": "https://api.buywhere.ai/mcp",
      "headers": {
        "Authorization": "Bearer <YOUR_TOKEN>"
      }
    }
  }
}

README

BuyWhere MCP Server — Product Search & Price Comparison for AI Agents

AI agents use BuyWhere to search products, compare prices, and discover deals across Singapore and US merchants in real time.

Install in 30 Seconds

bash
export BUYWHERE_API_KEY=bw_live_xxxxnpx -y @buywhere/mcp-server

Use with Claude Desktop, Cursor, VS Code Copilot, Cline, Windsurf, OpenCode, Codex, Continue.dev, and any MCP-compatible client.

[Get your free API key]

Or get one in 3 seconds, no signup, no email: POST /v1/auth/register · Legacy form: buywhere.ai/api-keys

[npm version] [npm downloads] [npm weekly downloads] [License: MIT] [Node version] [TypeScript] [GitHub stars] [Smithery] [MCP Registry] [Hashnode Blog]

AI Agents: Use This Package To

  • Search products across Singapore, US, Malaysia, Thailand, and Vietnam markets by keyword, category, or price range
  • Compare products across Lazada, Shopee, Amazon, and local retailers in a single query
  • Find deals and track real-time pricing with multi-currency support
  • Build shopping agents that recommend, compare, and link to products programmatically
  • Discover product catalogs with structured taxonomy for supported markets

Product search API for AI agents via Model Context Protocol. Built for AI agent commerce, not store management.

Official MCP Registry listing: io.github.BuyWhere/buywhere-mcp

Works with Claude Desktop, Cursor, VS Code Copilot, Cline, Windsurf, OpenCode, Codex, Continue.dev, and any MCP-compatible client. Also supports Agent-to-Agent (A2A) protocol.

Demo

[BuyWhere MCP in Claude Desktop]

44-second demo: product search, deal discovery, price comparison, and multi-region support.

text
User:   "Find me wireless earbuds under $50 available in Singapore"Agent:  [calls search_products → returns 5 matching products]
User:   "Compare the top 3"Agent:  [calls compare_products → side-by-side with best-value pick]

Quick Start

Get a key in 3 seconds — no signup, no email:

bash
# 1. Register (one call, returns api_key instantly)curl -X POST https://api.buywhere.ai/v1/auth/register \  -H "Content-Type: application/json" \  -d '{"agent_name":"your-agent"}'# → {"api_key":"bw_...","tier":"unverified","rate_limit":{"rpm":20,"daily":1000}}
# 2. Use the keyexport BUYWHERE_API_KEY=bw_...npx -y @buywhere/mcp-server

Legacy email signup (60s, manual approval) → buywhere.ai/api-keys

Tutorials

From the Blog

Read the BuyWhere Engineering Blog for deep dives on MCP architecture, agent commerce, and the ecosystem.

Also follow the BuyWhere Hashnode blog mirror for the same engineering content on Hashnode.

Tools

ToolDescription
search_productsSearch catalog by keyword, category, price, country
get_productFull product details by ID (prices, specs, images)
compare_productsSide-by-side comparison of 2–10 products
find_best_priceCheapest deliverable listing for a product across merchants
get_dealsProducts with significant price drops
list_categoriesAvailable product category taxonomy
find_similarSimilar products by vector similarity
ingest_productsSubmit product URLs for catalog ingestion (agents/merchants)
search_products_v2v2 search; requires deliver_to (ISO country)
get_product_v2v2 product details by ID
compare_products_v2v2 comparison; optional deliver_to
get_deals_v2v2 deals; requires deliver_to
find_best_price_v2v2 best price; requires deliver_to

Remote MCP: POST https://api.buywhere.ai/mcp (JSON-RPC 2.0, protocolVersion 2024-11-05, 13 tools). Glama listing: https://glama.ai/mcp/servers/BuyWhere/buywhere-mcp

MCP Client Configuration

Framework quickstarts:

Claude Desktop

Add to claude_desktop_config.json:

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

Cursor / VS Code / Cline

Add to your MCP settings file:

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

Windsurf

Add to ~/.windsurf/mcp.json:

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

OpenCode / Codex

Add to opencode.json:

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

Continue.dev (VS Code / JetBrains)

Add to ~/.continue/config.json:

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

Mastra

Mastra is a TypeScript-first AI agent framework with native MCP support.

bash
npm install @mastra/core @mastra/mcp
typescript
import { Mastra } from '@mastra/core';import { MastraMCPClient } from '@mastra/mcp';
const buywhere = new MastraMCPClient({  name: 'buywhere',  server: {    url: new URL('https://api.buywhere.ai/mcp'),    requestInit: {      headers: { 'Authorization': `Bearer ${process.env.BUYWHERE_API_KEY}` },    },  },});
const agent = new Mastra({  agents: {    shoppingAgent: {      instructions: 'You are a shopping assistant. Use BuyWhere to find and compare products.',      tools: await buywhere.tools(),    },  },});
const result = await agent.agents.shoppingAgent.generate(  'Find me the best deal on a Sony WH-1000XM5 in Singapore');

Full guide: BuyWhere + Mastra Integration

LangChain

Use BuyWhere tools in LangChain agents via the MCP adapter:

python
from langchain_mcp_adapters.client import MultiServerMCPClientfrom langgraph.prebuilt import create_react_agentfrom langchain_anthropic import ChatAnthropic
async def main():    async with MultiServerMCPClient({        "buywhere": {            "url": "https://api.buywhere.ai/mcp",            "transport": "streamable_http",            "headers": {"Authorization": f"Bearer {BUYWHERE_API_KEY}"},        }    }) as client:        tools = await client.get_tools()        agent = create_react_agent(ChatAnthropic(model="claude-sonnet-4-5"), tools)        result = await agent.ainvoke({"messages": [("user", "Find the cheapest Sony headphones in Singapore")]})

LlamaIndex

Connect BuyWhere via LlamaIndex MCP client:

python
from llama_index.tools.mcp import BasicMCPClient, McpToolSpecfrom llama_index.agent.openai import OpenAIAgent
async def main():    mcp_client = BasicMCPClient(        command_or_url="https://api.buywhere.ai/mcp",        headers={"Authorization": f"Bearer {BUYWHERE_API_KEY}"},    )    mcp_tool_spec = McpToolSpec(client=mcp_client)    tools = mcp_tool_spec.to_tool_list()    agent = OpenAIAgent.from_tools(tools)    response = await agent.achat("Compare prices for iPhone 16 Pro across Singapore and US")

CrewAI

Use BuyWhere in a CrewAI agent with MCP tool integration:

python
from crewai import Agent, Task, Crewfrom crewai_tools import MCPServerAdapter
buywhere_server = MCPServerAdapter(    server_params={        "url": "https://api.buywhere.ai/mcp",        "headers": {"Authorization": f"Bearer {BUYWHERE_API_KEY}"},        "transport": "streamable-http",    })
shopping_agent = Agent(    role="Shopping Research Analyst",    goal="Find the best deals across Singapore and US markets",    tools=[buywhere_server],)
task = Task(    description="Find the best price for Sony WH-1000XM5 headphones across all available markets",    agent=shopping_agent,    expected_output="Product comparison with prices and merchant links",)
crew = Crew(agents=[shopping_agent], tasks=[task])result = crew.kickoff()

Configuration

VariableDefaultDescription
BUYWHERE_API_KEY(required)API key (no signup: POST /v1/auth/register {"agent_name":"<name>"}) — returns instantly, no email verification
BUYWHERE_API_URLhttps://api.buywhere.ai/mcpCustom API base URL

Install

bash
# Run directly (no install)npx -y @buywhere/mcp-server
# Install globallynpm install -g @buywhere/mcp-serverbuywhere-mcp

Use Cases

  • Shopping agents — build AI agents that search, compare, recommend products across markets
  • Price comparison — multi-market pricing in a single query across Lazada, Shopee, Amazon, local retailers
  • Deal discovery — find best-value products with real-time pricing and inventory
  • Ecommerce automation — integrate product search into any MCP-compatible app
  • Cross-border commerce — compare prices between Singapore, US, Malaysia, Thailand, and Vietnam markets
  • Agent-to-Agent commerce — delegate shopping tasks between agents via A2A protocol

Architecture

Developer's AI Agent (Claude, Cursor, etc.)  │  ├── MCP Protocol (stdio)  │  ├── @buywhere/mcp-server  │     ├── search_products(q, category, min_price, max_price, country_code, deliver_to)  │     ├── get_product(product_id)  │     ├── compare_products(product_ids[])  │     ├── find_best_price(product_name, country_code, deliver_to)  │     ├── get_deals(country_code, deliver_to, category)  │     ├── list_categories()  │     ├── find_similar(product_id)  │     └── ingest_products(urls[])  │  └── BuyWhere API (api.buywhere.ai)        └── Product catalog across SG, US, MY, TH, and VN merchants

Development

bash
git clone https://github.com/BuyWhere/buywhere-mcp.gitcd buywhere-mcpnpm installnpm run buildnpm start

Why BuyWhere?

BuyWhere is a product search API for AI agents. We aggregate product data from Singapore, US, Malaysia, Thailand, and Vietnam merchants into a single, agent-friendly interface — no store management, no Shopify integration. Just search and compare products in real time.

  • One API — all markets, all retailers
  • Agent-native — built for MCP from day one
  • Real-time — live pricing and availability
  • Developer-first — no SDK needed, just add the server

Works Well With

These complementary MCP packages extend BuyWhere into powerful multi-tool workflows:

  • @modelcontextprotocol/server-filesystem — Save shopping results and product research to your local filesystem. Combine with BuyWhere to export deal lists, price comparisons, and product specs as structured files.
  • @supabase/mcp-server-supabase — Store favorite products, user preferences, and price alerts in Supabase. Persist shopping history across agent sessions.
  • n8n-mcp — Automate price monitoring workflows. Build no-code pipelines that watch BuyWhere prices and trigger notifications on price drops.
  • tavily-mcp — Research products before buying. Use Tavily to find reviews and comparisons, then use BuyWhere to get current prices and purchase links.
  • @playwright/mcp — E2E test your shopping agent interactions. Verify that product search, price comparison, and checkout flows work correctly in browser automation.

Protocols

ProtocolSupport
MCP (Model Context Protocol)Full support — 10 tools, stdio transport
A2A (Agent-to-Agent)Multi-agent task delegation — Agent Card

Contributing

See CONTRIBUTING.md for how to report issues, submit PRs, and suggest features.

From the Blog

Learn more about MCP servers and the BuyWhere ecosystem:

Support

If you find this project useful:

  • ⭐ Star the repo — it helps others discover BuyWhere
  • 🐛 Open an issue for bugs or feature requests
  • 💬 Start a discussion for questions or ideas
  • 📣 Share it with other developers who build AI agent tools

License

MIT

Source: README.md at commit 48b21e8

Tools

13

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.

Parametersqmodelimitquerydomainmarketoffsetregioncompactcountrycategorymax_price+3 more

get_product

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

Parametersidrequired

compare_products

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

Parametersidsrequired

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

Parameterslimitmarketoffsetregioncountrycategorycurrencydeliver_tocountry_codemin_discount

list_categories

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

Parametersmarketregioncountrycountry_code

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.

Parametersqmarketregioncountrycategorydeliver_tocountry_codeproduct_name

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.

Parameterslimitproduct_idrequired

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.

Parameterssourcerequiredproductsrequired

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.

Parametersqmodelimitquerydomainoffsetregioncompactcountrycategorymax_pricemin_price+2 more

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.

Parametersidrequireddeliver_torequired

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.

Parametersidsrequireddeliver_torequired

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.

Parameterslimitoffsetregioncountrycategorycurrencydeliver_torequiredcountry_codemin_discount

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.

Parametersqregioncountrycategorydeliver_torequiredcountry_codeproduct_name

Version history

1
  1. v1.2.0LatestSep 16, 2026

Score

100% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 daysRequired25 pts
  • Auth declaredRequired10 pts
  • Tools listedRequired15 pts
  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts