BuyWhere MCP Server

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

AI agents use BuyWhere to search 367M+ products across 932K+ merchants, compare prices, and discover deals in the United States and Singapore — with growing coverage across UK, EU, SEA, and AU — in real time.

Install in 30 Seconds

# Agents: get a key with zero human steps (no email):
# curl -X POST "https://api.buywhere.ai/v1/auth/register?verify=false" \
#   -H "Content-Type: application/json" -d '{"agent_name": "my-agent"}'
export BUYWHERE_API_KEY=bw_live_xxxx
npx -y @buywhere/mcp-server

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

• npm: https://www.npmjs.com/package/@buywhere/mcp-server
• GitHub: https://github.com/BuyWhere/buywhere-mcp
• MCP Registry: https://registry.modelcontextprotocol.io/?q=io.github.BuyWhere%2Fbuywhere-mcp

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

---

AI Agents: Use This Package To

• Search products across the United States and Singapore by keyword, category, or price range — with growing coverage across UK, EU, SEA, and AU
• Compare prices 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 any region

---

Build With BuyWhere Challenge — $5,000 in Prizes

Join the "Build With BuyWhere" AI Agent Developer Challenge! Use the BuyWhere MCP server to create AI agents that search, compare, and recommend products across the United States and Singapore — with growing coverage across UK, EU, SEA, and AU.

• Prize pool: $5,000 USD
• Deadline: June 30, 2026
• Challenge page: buywhere.ai/challenge

---

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

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

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_prices → side-by-side with best-value pick]

Quick Start

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

# 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 key
export BUYWHERE_API_KEY=bw_...
npx -y @buywhere/mcp-server

# 3. Call v2 tools — always pass deliver_to
search_products_v2({ query: "robot vacuum", deliver_to: "SG" })
find_best_price_v2({ query: "iphone 16", deliver_to: "US" })

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

Tutorials

• Part 1: MCP for Ecommerce — The Missing Infrastructure Layer for AI Agent Shopping — Architecture and why agents need a product catalog API
• Part 2: Build a Real Shopping Agent in 15 Minutes — Hands-on: set up MCP server, search products, compare prices, build a working agent

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.

• MCP for Ecommerce 2026 — How AI agents search real products, compare prices across markets, and why MCP is the standard
• Building Production MCP Servers — Architecture, tool design patterns, and distribution from 0 to 1,700+ daily npm downloads
• MCP Server Ecosystem 2026 — Every MCP category mapped (4,800+ servers across 40+ domains)
• AI Agent Commerce: Missing Infrastructure — Why shopping is the last unbuilt layer of the agent-native economy
• Cross-Border Price Comparison Tutorial — Build a shopping agent in 10 minutes with BuyWhere MCP

Tools

Tool	Description
search_products	Search catalog by keyword, category, price, region
get_product	Full product details by ID (prices, specs, images)
compare_prices	Side-by-side comparison of 2–5 products
get_price	Current prices across all merchants for one product
get_affiliate_link	Click-tracked affiliate URL for a product
get_catalog	Available product category taxonomy

v2 — deliver_to Required

The v2 tool surface requires an end-user country code (deliver_to) on every search, price, and deals call so results are ranked for shippable products in that market. Calls without deliver_to return error -32602 INVALID_PARAMETER.

Tool	Required Params	Description
search_products_v2	query, deliver_to	Search catalog filtered to end-user's market (SG, US, MY, etc.)
get_product_v2	product_id	Full product details with per-row availability for the scoped market
compare_products_v2	ids[]	Compare 2–10 products, scoped to a market via deliver_to
find_best_price_v2	query, deliver_to	Return the single cheapest shippable listing
get_deals_v2	deliver_to	All products with ≥20% price drops, filtered to shippable in market

# v2 call — always include deliver_to (ISO 3166-1 alpha-2)
search_products_v2({ query: "robot vacuum", deliver_to: "SG" })
find_best_price_v2({ query: "iphone 16", deliver_to: "US" })
get_deals_v2({ deliver_to: "MY" })

# v1 is still available (legacy)
search_products({ query: "robot vacuum" })

MCP Client Configuration

Framework quickstarts:

• CrewAI: API key · BuyWhere quickstart
• Mastra: API key · BuyWhere quickstart

Claude Desktop

Add to claude_desktop_config.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:

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

Windsurf

Add to ~/.windsurf/mcp.json:

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

OpenCode / Codex

Add to opencode.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:

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

npm install @mastra/core @mastra/mcp

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:

from langchain_mcp_adapters.client import MultiServerMCPClient
from langgraph.prebuilt import create_react_agent
from 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:

from llama_index.tools.mcp import BasicMCPClient, McpToolSpec
from 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 US and Singapore")

CrewAI

Use BuyWhere in a CrewAI agent with MCP tool integration:

from crewai import Agent, Task, Crew
from 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 US and Singapore markets (UK, EU, SEA, and AU expanding)",
    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

Variable	Default	Description
BUYWHERE_API_KEY	(required)	API key (no signup: POST /v1/auth/register {"agent_name":"<name>"}) — returns instantly, no email verification
BUYWHERE_API_URL	https://api.buywhere.ai/mcp	Custom API base URL

Install

v2 tools require deliver_to — on the v2 surface (search, find_best_price, get_deals), every call must include the end-user's ISO 3166-1 alpha-2 country code so results are ranked for shippable products. Omitting it returns error -32602 INVALID_PARAMETER.

# Run directly (no install)
npx -y @buywhere/mcp-server

# Install globally
npm install -g @buywhere/mcp-server
buywhere-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 the United States and Singapore, with growing coverage across UK, EU, SEA, and AU
• Agent-to-Agent commerce — delegate shopping tasks between agents via A2A protocol

Architecture

Developer's AI Agent (Claude, Cursor, etc.)
  │
  ├── MCP Protocol (stdio or streamable-http)
  │
  ├── @buywhere/mcp-server
  │     ├── search_products_v2(q, deliver_to)   # v2: requires deliver_to
  │     ├── get_product_v2(product_id)
  │     ├── compare_products_v2(ids[], deliver_to)
  │     ├── find_best_price_v2(q, deliver_to)   # v2: requires deliver_to
  │     ├── get_deals_v2(deliver_to)             # v2: requires deliver_to
  │     ├── get_product(product_id)             # v1: still available
  │     ├── compare_prices(product_ids[])
  │     └── get_catalog()
  │
  └── BuyWhere API (api.buywhere.ai)
        └── Product catalog across US and Singapore merchants (UK, EU, SEA, and AU expanding)

Development

git clone https://github.com/BuyWhere/buywhere-mcp.git
cd buywhere-mcp
npm install
npm run build
npm start

Why BuyWhere?

BuyWhere is a product search API for AI agents. We aggregate 367M+ products from 932K+ merchants in the United States and Singapore — with growing coverage across UK, EU, SEA, and AU — 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

Protocol	Support
MCP (Model Context Protocol)	Full support — 11 tools (6 v1 + 5 v2), stdio + streamable-http transports
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:

• MCP server discovery — Understanding the MCP server discovery gap
• Building production MCP servers — Production best practices for MCP servers
• MCP servers that earn their context window — MCP servers that maximize context window value
• MCP ecommerce guide — Definitive guide to MCP for ecommerce
• BuyWhere MCP launch — Announcing the BuyWhere MCP server launch
• MCP server ecosystem 2026 — Complete guide to the MCP server ecosystem in 2026

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