Building an AI shopping agent with retailerapi MCP (2026 guide)

By mid-2026 the "AI agent that helps people shop" category has gone from speculative to crowded. Perplexity Shopping, Amazon Rufus, Google's AI Overviews, OpenAI's ChatGPT Shopping mode, and a long tail of ambitious indie agents are all in market. They mostly suffer from the same problem: the underlying product data is scraped on the fly, hallucinated, or stale.

If you are building an AI shopping agent, the data layer is the bottleneck. retailerapi's MCP server gives you six product-data tools that work today, return verifiable retailer prices, and bill predictably by token. This guide walks you through wiring one up.

What you'll build

In about 5 minutes, an agent inside Claude Code (or Cursor, or any MCP client) that can:

1. Take a product identifier from the user (UPC, item_id, even just a product title)
2. Look up the canonical product
3. Pull current pricing from Walmart, Amazon (when available), eBay, Target, Best Buy, Lowe's, and Home Depot
4. Pull 30-day price history
5. Identify the best buying option, current spread, and historical context
6. Return a clean recommendation with citations to retailer URLs

Prerequisites

• A retailerapi account (sign up free)
• An API key
• Claude Code, Claude Desktop, Cursor, or any other MCP-compatible client
• Node 20+

Step 1: Install the MCP server

The MCP server is published to npm. Most clients run it via npx:

{
  "mcpServers": {
    "retailerapi": {
      "command": "npx",
      "args": ["-y", "@retailerapi/mcp"],
      "env": {
        "RETAILERAPI_KEY": "rk_live_YOUR_KEY"
      }
    }
  }
}

Drop that into your client's MCP config (see the MCP setup post for client-specific paths). Restart the client.

Step 2: Verify the tools loaded

In Claude Code, run /mcp to list connected servers. You should see retailerapi with 5 tools: lookup_product, price_history, get_offers, get_seller, get_reviews.

In Cursor, the agent's tool palette should show the same 6 entries.

Step 3: First test query

Ask the agent something concrete:

"Use retailerapi to look up UPC 728028502244. What is the current Walmart price and how many sellers are listing it?"

The agent will call lookup_product once with identifier=728028502244. Expected response shape:

{
  "item_id": "...",
  "title": "Tailgater II Portable Gas Fire Pit with Beat to Music...",
  "brand": "Outland Living",
  "image": "https://i5.walmartimages.com/...",
  "current_price": 217.45,
  "buybox_price": 217.45,
  "offers_count": 3,
  "walmart_url": "https://www.walmart.com/ip/...",
  "queried_identifier": "728028502244"
}

The agent synthesizes a natural-language answer and you've confirmed the integration works. Token cost: ~2 tokens.

Step 4: Add cross-retailer comparison

Same product, this time asking for the multi-retailer view:

"Now check that same product on Amazon, eBay, Target, Best Buy, Lowe's, and Home Depot. Tell me the cheapest option and the spread."

The agent will re-call lookup_product with include_cross_retailer=true. Response shape adds:

{
  ...
  "cross_retailer": [
    { "retailer": "amazon", "status": "ok", "price": 234.99, "url": "..." },
    { "retailer": "ebay", "status": "ok", "price": 199.50, "url": "..." },
    { "retailer": "target", "status": "not_found" },
    { "retailer": "bestbuy", "status": "indexing" },
    ...
  ]
}

Status values:

• ok — Data is current
• stale — Data is past TTL (background refresh in flight)
• indexing — First lookup; no data yet (call again in 30 seconds)
• not_found — Retailer doesn't carry this product
• blocked / error — Transient retailer-side issue

Token cost: ~10 tokens for the enriched lookup.

Step 5: Add price-history context

"Pull the 30-day price history for this product on Walmart and tell me if the current price is at, near, or above the historical average."

The agent calls price_history with identifier=728028502244&timeframe=30d&retailer=walmart. Response is an array of {observed_at, price, in_stock} rows, typically 30 to 60 entries.

The agent computes mean, min, max, and tells you whether the current price is at the 90-day low (a buy signal), near the historical average (neutral), or near the high (wait).

Token cost: 2 tokens for the lookup + 0 to 2 for inline reasoning.

Step 6: Wire it into your real workflow

The interesting use cases:

Sourcing scout. Daily prompt to your agent: "Check the current price on these 50 UPCs across all retailers. Flag any where Walmart is at least $20 cheaper than the next-lowest retailer." Agent loops lookup_product, builds the table, returns it. Token spend: ~500 tokens for 50 products with cross_retailer enabled. At free-tier rates that's about 1/2 your monthly budget; at the $49/mo tier it's a rounding error.

Repricing trigger. Agent watches your inventory list. Each morning, calls price_history for each of your 200 active SKUs, identifies items that dropped >5% on Amazon in the last 7 days (likely your competitor adjusted), and queues a repricing recommendation in your repricer of choice.

Buyer's-club personal shopper. Subscribers prompt your agent with "find me a deal on a 6-quart pressure cooker." Agent issues a few lookup_product calls on candidate UPCs, filters on cross_retailer for the lowest-price retailer, returns a ranked list with affiliate-tagged URLs. Tokens scale with the breadth of the catalog you're searching.

Cross-retailer arbitrage research. Agent ingests a list of seller candidate UPCs, runs lookup_product with cross_retailer for each, computes margin against Amazon FBA fees + Walmart 2DS fees + shipping, ranks by expected profit. Replaces hours of manual spreadsheet work.

Token economics

For each agent prompt that triggers a single lookup_product with cross_retailer:

• Free tier (1,000 tokens, no expiration): ~100 enriched lookups
• $49/mo tier (864,000 tokens / 30d): ~86,000 enriched lookups
• $429/mo tier (10,800,000 tokens / 30d): ~1,000,000+ enriched lookups

For batch agents running through 100s of SKUs, plan on the $119/mo or $429/mo tier. For human-in-the-loop one-off shopping queries, the free tier is genuinely free.

What ships next

• bulk_lookup (rolling out August 2026) — submit up to 1,000 UPCs in a single call at a discounted token rate. Solves the "agent loops 200 times" pattern.
• compare_retailers (June 2026) — single tool that returns the cross-retailer comparison directly, without requiring the agent to chain lookup_product and parse cross_retailer.
• watch_product (July 2026) — server-side price-drop alerts via webhook, freeing the agent from polling.

Source code

The MCP server is open at github.com/retailerapi/mcp under MIT. The TypeScript SDK is at github.com/retailerapi/sdk. Both accept contributions.

Try it

Sign up free, grab a key, and have your first AI-powered cross-retailer comparison running in 5 minutes.