buywhere-mcp

MCP server for the BuyWhere product catalog. Lets Claude Desktop, Cursor, Windsurf, and other MCP-compatible agents search and retrieve products without writing any HTTP code.

Setup

1. Get your API key

2. Configure your client

Claude Desktop

Open ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows) and add:

{
  "mcpServers": {
    "buywhere": {
      "command": "python",
      "args": ["mcp_server.py"],
      "env": {
        "BUYWHERE_API_KEY": "your_api_key_here"
      }
    }
  }
}

Cursor

Open Settings → MCP and add a new server, or edit ~/.cursor/mcp.json:

{
  "mcpServers": {
    "buywhere": {
      "command": "python",
      "args": ["mcp_server.py"],
      "env": {
        "BUYWHERE_API_KEY": "your_api_key_here"
      }
    }
  }
}

Windsurf

Edit ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "buywhere": {
      "command": "python",
      "args": ["mcp_server.py"],
      "env": {
        "BUYWHERE_API_KEY": "your_api_key_here"
      }
    }
  }
}

3. Ask your agent to search products

Restart your client, then try:

"Search BuyWhere for wireless earbuds under $50 in Singapore"

"Use BuyWhere to compare the cheapest iPhone 15 cases"

"Get me the affiliate link for product ID abc123 from BuyWhere"

Tools

`search_products`

Search the BuyWhere catalog using keywords or natural language.

Parameter	Type	Required	Description
`query`	string	yes	Keyword or natural-language query
`country`	string	no	Country code hint (`sg`, `my`, `id`)
`category`	string	no	Category slug (e.g. `electronics/smartphones`)
`limit`	integer	no	Max results, 1–50 (default 10)

`get_product`

Fetch full details for a single product.

Parameter	Type	Required	Description
`product_id`	string	yes	BuyWhere product ID

`get_price`

Compare current prices for a product across all available merchants. Returns listings ranked by total price (including shipping), plus best-price and best-value recommendations.

Parameter	Type	Required	Description
`product_id`	string	yes	BuyWhere product ID

`compare_prices`

Side-by-side comparison of 2–5 products. Returns structured differentiators, price range, pros/cons, and a best-value recommendation — purpose-built for AI agent decision-making.

Parameter	Type	Required	Description
`product_ids`	string[]	yes	Array of 2–5 BuyWhere product IDs

`get_affiliate_link`

Get the click-tracked BuyWhere affiliate link for a product. Always use this instead of raw product URLs when sharing links with users — it logs the referral and redirects to the merchant page.

Parameter	Type	Required	Description
`product_id`	string	yes	BuyWhere product ID

`get_catalog`

List available product categories. Use this to discover what categories exist before searching or filtering.

Parameter	Type	Required	Description
`parent_slug`	string	no	Parent slug for subcategories (omit for top-level)

Resources

URI	Description
`buywhere://catalog/sg`	Available categories in Singapore
`buywhere://catalog/my`	Available categories in Malaysia
`buywhere://catalog/id`	Available categories in Indonesia

Environment variables

Variable	Required	Description
`BUYWHERE_API_KEY`	yes	Your BuyWhere API key
`BUYWHERE_API_URL`	no	Override API base URL (default: `https://api.buywhere.ai`)

Sample agent conversation

User: Find the cheapest mechanical keyboard on BuyWhere and compare the top 2

Claude: I'll search BuyWhere for mechanical keyboards and compare the top results.

[Calls search_products with query="mechanical keyboard", limit=5]

Found 12 products. Top results:
1. Keychron K2 — SGD 89.00 (prod_abc123)
2. Royal Kludge RK61 — SGD 65.00 (prod_def456)

[Calls compare_prices with product_ids=["prod_abc123", "prod_def456"]]

Comparison: Keychron K2 vs Royal Kludge RK61
Price range: SGD 65 – SGD 89
Key differences:
  • Keychron K2: full-size TKL layout, Mac-optimised keycaps
  • RK61: compact 60% layout, budget-friendly
Best value: Royal Kludge RK61 at SGD 65

[Calls get_affiliate_link with product_id="prod_def456"]

Here's your purchase link: https://api.buywhere.ai/r/prod_def456

Development

npm install
npm run build
BUYWHERE_API_KEY=your_key python mcp_server.py