Buywhere Mcp

io.github.BuyWhere由 GitHub 帳號 BuyWhere 發布v1.2.0更新於 Oct 24, 2026

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

已驗證Streamable HTTP可網頁執行網頁搜尋與抓取商業與電商

概覽

AI 產生的概覽

BuyWhere 讓助理搜尋涵蓋新加坡、美國及東南亞市場的商品目錄，跨商家比價並找出折扣，適合打造購物與比價類智慧代理。

可以做什麼
依關鍵字、分類和價格搜尋商品目錄，面向買家時須提供 deliver_to 國家參數，並可列出分類體系。取得單一商品的完整詳情與目前價格，並依價格、品牌、評分和分類並排比較多個商品。找出跨商家最低可配送報價，並依折扣比例列出促銷商品。以向量相似度找出相似商品作為推薦。批次寫入或更新商品項目，此操作需要具備 ingest 權限的 API 金鑰。
適用情境
適合打造需要新加坡、美國、馬來西亞、泰國或越南市場即時商品、折扣與商家報價資料的購物或比價智慧代理，也適合讓助理回答某商品在哪裡買最便宜之類的問題。
執行需求
需要 BuyWhere API 金鑰：本機 npm 套件透過環境變數 BUYWHERE_API_KEY 提供，遠端端點透過 Authorization bearer 權杖提供。金鑰可於註冊端點免註冊取得。本機套件透過 npx 執行，需要 Node.js；遠端端點需要網路存取。
安裝前請注意
API 金鑰屬於機密，應避免寫入共用設定或日誌。ingest_products 會寫入商品目錄，需要具備 ingest 權限的金鑰，應僅在可信情境使用。商品結果包含經點擊追蹤器導向的外部連結，查詢內容與國家資料會傳送至 BuyWhere 伺服器。

安裝

在 SourceWeft 中

  1. 開啟 儀表板中的 Buywhere Mcp，將其新增到工作區。
  2. 連接 Authorization token 憑證。它們會被私密儲存，絕不會在公開頁面上展示。
  3. 為需要使用其工具的對話啟用該服務。

Web executable，透過 Streamable HTTP。 遠端服務在工作區中設定後即可從網頁執行環境執行。

交給代理程式安裝

把這段提示詞貼上到 Claude Code、Codex、Cursor 等代理程式，或 SourceWeft 對話中。代理程式會讀取該伺服器的安裝指南，先向你展示發布者、端點和登入方式，經你同意後再把它新增到你的客戶端。金鑰不會寫進任何命令。

閱讀 https://sourceweft.com/mcp/io.github.BuyWhere%2Fbuywhere-mcp/install.md，並按其中說明把這個 MCP 伺服器接入我的客戶端。修改任何設定之前，先告訴我它的發布者、端點和登入方式，等我確認。不要把 API 金鑰寫進命令或我會提交的檔案；問我金鑰應從哪裡取得。

檢視代理程式所依據的安裝指南

其他 MCP 客戶端

把它新增到你客戶端的 mcpServers 設定中。

{
  "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

來源：README.md，提交 48b21e8

工具

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.

輸入參數qmodelimitquerydomainmarketoffsetregioncompactcountrycategorymax_price另有 3 個

get_product

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

輸入參數id必填

compare_products

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

輸入參數ids必填

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

輸入參數limitmarketoffsetregioncountrycategorycurrencydeliver_tocountry_codemin_discount

list_categories

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

輸入參數marketregioncountrycountry_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.

輸入參數qmarketregioncountrycategorydeliver_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.

輸入參數limitproduct_id必填

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.

輸入參數source必填products必填

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.

輸入參數qmodelimitquerydomainoffsetregioncompactcountrycategorymax_pricemin_price另有 2 個

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.

輸入參數id必填deliver_to必填

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.

輸入參數ids必填deliver_to必填

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.

輸入參數limitoffsetregioncountrycategorycurrencydeliver_to必填country_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.

輸入參數qregioncountrycategorydeliver_to必填country_codeproduct_name

版本歷史

1
  1. v1.2.0最新Sep 16, 2026

評分

已滿足適用檢查項的 100%

該評分衡量此收錄條目的完整程度，依據註冊中心條目、端點與公開來源計算得出。它不是對伺服器本身的評價，也不表示伺服器安全或目前可用：可連通性是帶日期的檢查結果，評分也不包含安裝量或使用者評價。

  • 近 30 天內可連通必需25 分
  • 已宣告認證方式必需10 分
  • 已列出工具必需15 分
  • 描述必需15 分
  • 圖示10 分
  • 文件15 分
  • 授權條款10 分