# 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_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}

[![npm version](https://img.shields.io/npm/v/@buywhere/mcp-server.svg)](https://www.npmjs.com/package/@buywhere/mcp-server) [![npm downloads](https://img.shields.io/npm/dm/@buywhere/mcp-server.svg)](https://www.npmjs.com/package/@buywhere/mcp-server) [![npm weekly downloads](https://img.shields.io/npm/dw/@buywhere/mcp-server?label=downloads%2Fweek)](https://www.npmjs.com/package/@buywhere/mcp-server) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) [![Node version](https://img.shields.io/badge/node-%3E%3D18-green)](https://nodejs.org) [![TypeScript](https://img.shields.io/badge/TypeScript-5.9-blue)](https://www.typescriptlang.org) [![GitHub stars](https://img.shields.io/github/stars/BuyWhere/buywhere-mcp?style=social)](https://github.com/BuyWhere/buywhere-mcp) [![Smithery](https://smithery.ai/badge/@BuyWhere/buywhere-mcp)](https://smithery.ai/servers/@buywhere/mcp-server) [![MCP Registry](https://img.shields.io/badge/MCP%20Registry-published-blue)](https://registry.modelcontextprotocol.io/?q=io.github.BuyWhere%2Fbuywhere-mcp) [![Hashnode Blog](https://img.shields.io/badge/Hashnode-Blog-2962FF?logo=hashnode&logoColor=white)](https://buywhere.hashnode.dev/) --- ## 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](https://modelcontextprotocol.io). Built for AI agent commerce, not store management. Official MCP Registry listing: [io.github.BuyWhere/buywhere-mcp](https://registry.modelcontextprotocol.io/?q=io.github.BuyWhere%2Fbuywhere-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)](https://github.com/google/A2A) protocol. --- ## Demo ![BuyWhere MCP in Claude Desktop](https://raw.githubusercontent.com/BuyWhere/buywhere-mcp/main/public/assets/demo/buywhere-mcp-claude-desktop.gif) *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 key export BUYWHERE_API_KEY=bw_... npx -y @buywhere/mcp-server ``` Legacy email signup (60s, manual approval) → [buywhere.ai/api-keys](https://buywhere.ai/api-keys) ## Tutorials - **[Part 1: MCP for Ecommerce — The Missing Infrastructure Layer for AI Agent Shopping](https://dev.to/buywhere/mcp-for-ecommerce-the-missing-infrastructure-layer-for-ai-agent-shopping-1i7d)** — Architecture and why agents need a product catalog API - **[Part 2: Build a Real Shopping Agent in 15 Minutes](https://dev.to/buywhere/mcp-for-ecommerce-part-2-build-a-real-shopping-agent-in-15-minutes-4f5b)** — Hands-on: set up MCP server, search products, compare prices, build a working agent ## From the Blog Read the **[BuyWhere Engineering Blog](https://buywhere.ai/blog)** for deep dives on MCP architecture, agent commerce, and the ecosystem. Also follow the **[BuyWhere Hashnode blog mirror](https://buywhere.hashnode.dev/)** for the same engineering content on Hashnode. - **[MCP for Ecommerce 2026](https://buywhere.ai/blog/mcp-for-ecommerce-2026)** — How AI agents search real products, compare prices across markets, and why MCP is the standard - **[Building Production MCP Servers](https://buywhere.ai/blog/building-production-mcp-servers)** — Architecture, tool design patterns, and distribution (verified ~1,050 npm downloads/month) - **[MCP Server Ecosystem 2026](https://buywhere.ai/blog/mcp-server-ecosystem-2026)** — Every MCP category mapped (4,800+ servers across 40+ domains) - **[AI Agent Commerce: Missing Infrastructure](https://buywhere.ai/blog/ai-agent-commerce-missing-infrastructure)** — Why shopping is the last unbuilt layer of the agent-native economy - **[Cross-Border Price Comparison Tutorial](https://buywhere.ai/blog/cross-border-price-comparison-agent-tutorial)** — Build a shopping agent in 10 minutes with BuyWhere MCP ## Tools | Tool | Description | |------|-------------| | `search_products` | Search catalog by keyword, category, price, country | | `get_product` | Full product details by ID (prices, specs, images) | | `compare_products` | Side-by-side comparison of 2–10 products | | `find_best_price` | Cheapest deliverable listing for a product across merchants | | `get_deals` | Products with significant price drops | | `list_categories` | Available product category taxonomy | | `find_similar` | Similar products by vector similarity | | `ingest_products` | Submit product URLs for catalog ingestion (agents/merchants) | | `search_products_v2` | v2 search; requires `deliver_to` (ISO country) | | `get_product_v2` | v2 product details by ID | | `compare_products_v2` | v2 comparison; optional `deliver_to` | | `get_deals_v2` | v2 deals; requires `deliver_to` | | `find_best_price_v2` | v2 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: - CrewAI: [API key](https://buywhere.ai/api-keys) · [BuyWhere quickstart](https://github.com/BuyWhere/buywhere-mcp#quick-start) - Mastra: [API key](https://buywhere.ai/api-keys) · [BuyWhere quickstart](https://github.com/BuyWhere/buywhere-mcp#quick-start) ### 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](https://mastra.ai) 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](https://api.buywhere.ai/docs/guides/mastra-integration) ### LangChain Use BuyWhere tools in LangChain agents via the MCP adapter: ```python 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: ```python 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 Singapore and US") ``` ### CrewAI Use BuyWhere in a CrewAI agent with MCP tool integration: ```python 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 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 | Variable | Default | Description | |----------|---------|-------------| | `BUYWHERE_API_KEY` | (required) | API key (no signup: `POST /v1/auth/register {"agent_name":""}`) — returns instantly, no email verification | | `BUYWHERE_API_URL` | `https://api.buywhere.ai/mcp` | Custom API base URL | ## Install ```bash # 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 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.git cd buywhere-mcp npm install npm run build npm 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](https://www.npmjs.com/package/@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](https://www.npmjs.com/package/@supabase/mcp-server-supabase)** — Store favorite products, user preferences, and price alerts in Supabase. Persist shopping history across agent sessions. - **[n8n-mcp](https://www.npmjs.com/package/n8n-mcp)** — Automate price monitoring workflows. Build no-code pipelines that watch BuyWhere prices and trigger notifications on price drops. - **[tavily-mcp](https://www.npmjs.com/package/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](https://www.npmjs.com/package/@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 — 10 tools, stdio transport | | **A2A** (Agent-to-Agent) | Multi-agent task delegation — [Agent Card](https://buywhere.ai/.well-known/agent.json) | ## Contributing See [CONTRIBUTING.md](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](https://buywhere.hashnode.dev/the-mcp-server-discovery-gap) — Understanding the MCP server discovery gap - [Building production MCP servers](https://buywhere.hashnode.dev/building-production-mcp-servers) — Production best practices for MCP servers - [MCP servers that earn their context window](https://buywhere.hashnode.dev/5-mcp-servers-that-earn-context-window) — MCP servers that maximize context window value - [MCP ecommerce guide](https://buywhere.hashnode.dev/mcp-for-ecommerce-definitive-guide) — Definitive guide to MCP for ecommerce - [BuyWhere MCP launch](https://buywhere.hashnode.dev/buywhere-mcp-goes-live) — Announcing the BuyWhere MCP server launch - [MCP server ecosystem 2026](https://buywhere.hashnode.dev/mcp-server-ecosystem-2026-complete-guide) — 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](https://github.com/BuyWhere/buywhere-mcp/issues/new) for bugs or feature requests - 💬 [Start a discussion](https://github.com/BuyWhere/buywhere-mcp/discussions) for questions or ideas - 📣 Share it with other developers who build AI agent tools ## License MIT