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 分