MCP Integration

BuyWhere works natively with Claude Desktop, Cursor, Windsurf, and any Model Context Protocol (MCP) client. This guide shows you how to set it up.

Available Tools

The BuyWhere MCP server exposes 13 tools (8 v1, 5 v2):

The deliver_to Parameter

Every v2 tool requires deliver_to. It is the buyer's ISO 3166-1 alpha-2 country code (uppercase).

deliver_to: "SG" | "US" | "MY" | "TH" | "VN" | "PH" | "ID" | "GB" | ...

Why deliver_to matters

• Filters undeliverable products — results that cannot ship to the buyer are excluded
• Ranks local-first — products from merchants in the buyer's country appear first
• Adds availability labels — each result carries availability: "local" | "ships_to_you" | "unavailable" | "unknown" backed by verified shipping policies for 28,000+ stores
• Prevents all-market scans — without it, results span all countries and may be undeliverable

Always pass the end user's country, not the product's origin country.

Migrating from v1 to v2

v1 tools are deprecated and will stop accepting calls on 2026-12-31Z. Migrating takes two changes:

1. Rename the tool

2. Add deliver_to

Add deliver_to to every v2 tool call with the buyer's country:

// v1 call
{
  "name": "search_products",
  "arguments": { "q": "wireless headphones", "country_code": "SG" }
}

// v2 call — add deliver_to
{
  "name": "search_products_v2",
  "arguments": { "q": "wireless headphones", "deliver_to": "SG" }
}

// v1 call
{
  "name": "find_best_price",
  "arguments": { "q": "iphone 15 pro" }
}

// v2 call — add deliver_to, get shopping_job_id for multi-merchant handoff
{
  "name": "find_best_price_v2",
  "arguments": { "q": "iphone 15 pro", "deliver_to": "SG" }
}

Note: In v2 tools, deliver_to takes precedence over country_code/country and determines buyer-market ranking and availability labels. You can omit country_code in v2 calls — deliver_to is the canonical market parameter.

Setup: Claude Desktop

1. Get a BuyWhere API key at buywhere.ai/api-keys — or let your agent self-register in one call (no email, no human): curl -X POST "https://api.buywhere.ai/v1/auth/register?verify=false" -H "Content-Type: application/json" -d '{"agent_name":"my-agent"}'

2. Open your Claude Desktop config file:

   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows: %APPDATA%\Claude\claude_desktop_config.json

3. Add the BuyWhere MCP server:

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

1. Restart Claude Desktop.

Setup: Cursor

Add to your Cursor MCP settings (.cursor/mcp.json):

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

Setup: Claude Code

Add to your Claude Code MCP settings:

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

Try It

Once connected, ask your AI agent:

"Find me the cheapest wireless headphones in Singapore under $200"

"Compare the Sony WH-1000XM5 with the Bose QuietComfort Ultra"

"What are the best electronics deals right now?"

"Track the price history for this laptop over the last 30 days"

The agent will automatically use BuyWhere v2 tools with deliver_to to search products, compare prices, and find deals for your buyer market.

Using the TypeScript SDK

For programmatic agent integrations, use the TypeScript SDK:

npm install @buywhere/sdk

import { BuyWhereClient } from '@buywhere/sdk';

const client = new BuyWhereClient({
  apiKey: process.env.BUYWHERE_API_KEY,
});

// v2: always pass deliver_to
const results = await client.search.search({
  q: 'mechanical keyboard',
  deliver_to: 'SG', // REQUIRED in v2
  limit: 5,
});

console.log(results.products);

Using the LangChain Integration

npm install @buywhere/buywhere-langchain

import { BuyWhereTools } from '@buywhere/buywhere-langchain';

const tools = new BuyWhereTools({
  apiKey: process.env.BUYWHERE_API_KEY,
});

// Tools are v2 by default — deliver_to is passed per-call
const agent = createAgent({
  tools: tools.getTools(),
  // ...
});

OpenAI Function Calling

Use the OpenAPI spec directly for OpenAI function calling:

GET https://api.buywhere.ai/openapi.json

A ChatGPT Actions-compatible version is available at:

GET https://api.buywhere.ai/chatgpt-openapi.json

Discovery Endpoints

BuyWhere exposes standard discovery endpoints for AI agent platforms:

Next Steps

• Getting Started — get your API key and make your first call
• API Reference — full endpoint documentation
• Build a Price Comparison Tool — Python quickstart