Using the retailerapi MCP server in Claude Desktop, Claude Code, and Cursor

The Model Context Protocol (MCP) is the open standard Anthropic released in November 2024 for giving AI assistants access to tools. By May 2026 it is supported in Claude Desktop, Claude Code, Cursor, Cline, Continue, and a long tail of other agents. retailerapi ships an MCP server (@retailerapi/mcp) that exposes six product-data tools. Once installed, you can ask Claude things like "what is the current Walmart price of UPC 194629116676 and how does it compare to Amazon" and get a real answer with real data, not a confabulated guess.

This guide walks through the setup for each of the three most common MCP clients. Total setup time per client: about 60 seconds.

What you get

Five tools, all returning structured JSON to the model:

1. lookup_product — Resolve a UPC, EAN, ISBN, or Walmart item_id into title, brand, image, current price, offers count, walmart_url. Set include_cross_retailer=true to add Amazon, eBay, Lowe's, Target, Best Buy, Home Depot status and price.
2. price_history — Return the price-history time series for a product. Configurable timeframe (7d, 30d, 90d, 1y, all).
3. get_offers — Return the current seller list for a Walmart item (buy-box owner, alternate sellers, prices).
4. get_seller — Return profile info for a Walmart seller (rating, listing count, return policy).
5. get_reviews — Return product reviews summary (rating distribution, top quotes, total review count).

All tools are token-billed against your retailerapi account. The free tier (1,000 tokens, no expiration) covers about 200 lookups, enough to evaluate the integration before paying anything.

Prerequisites

1. A retailerapi account. Sign up free — magic link, no card.
2. An API key from your dashboard at app.retailerapi.com/app/keys.
3. Node.js 20 or newer installed locally.

Claude Desktop

Claude Desktop reads MCP server config from a single JSON file. Setup time: about 45 seconds.

1. Open the config file.

On macOS:

open -a "TextEdit" ~/Library/Application\ Support/Claude/claude_desktop_config.json

On Windows:

notepad $env:APPDATA\Claude\claude_desktop_config.json

2. Add the retailerapi server entry.

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

3. Quit and reopen Claude Desktop. The MCP server starts automatically on launch.

4. Verify in the app. Click the tools icon in the chat input. You should see "retailerapi" in the list with 6 tools available. Ask Claude something like "Use retailerapi to look up UPC 194629116676. What's the current price?" and it should call lookup_product and return a real answer.

Claude Code

Claude Code (the CLI) reads MCP config from ~/.claude/mcp.json or via the claude mcp add command. Setup time: about 30 seconds.

claude mcp add retailerapi \
  --command npx \
  --args "-y,@retailerapi/mcp" \
  --env RETAILERAPI_KEY=rk_live_YOUR_KEY_HERE

Or edit ~/.claude/mcp.json directly:

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

Restart your Claude Code session and the tools become available immediately. Use them by referencing the tool name in a prompt: "call retailerapi lookup_product with identifier 19667262713."

Cursor

Cursor's MCP support landed in early 2025. Settings live in ~/.cursor/mcp.json. Setup time: about 45 seconds.

1. Open the file.

mkdir -p ~/.cursor && nano ~/.cursor/mcp.json

2. Add the server.

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

3. Restart Cursor. Open a new chat and the retailerapi tools are available to the agent.

Cline, Continue, and other MCP clients

Most MCP clients use the same config schema (command + args + env). The @retailerapi/mcp package is stdio-transport, which is the universal default. If your client supports stdio MCP servers, the same JSON snippet above will work.

Common usage patterns

Sales-arb research inside Claude Desktop:

"Use retailerapi to look up UPC 728028502244. Then check if it's available on Amazon and Lowe's. What's the spread?"

Claude will call lookup_product once with include_cross_retailer=true, parse the result, and report back. Total tokens: ~10. Round trip: 2 to 4 seconds.

Price-drop monitoring inside Claude Code:

"Pull the 30-day price history for item 19667262713. Plot it as ASCII or list the local minima."

Claude calls price_history with timeframe=30d, then synthesizes the response. Useful for quick sanity checks while writing arbitrage scripts.

Cross-retailer reconnaissance inside Cursor:

"I'm building a feature that compares Walmart and Lowe's pricing for power tools. Show me what the retailerapi response shape looks like for UPC 681131243506."

Cursor's agent will call lookup_product and return the JSON, which you can then use to scaffold your TypeScript types.

Troubleshooting

"Tool calls failing with 401 unauthorized" — Your API key is wrong or expired. Check at app.retailerapi.com/app/keys.

"Tool calls failing with 429 rate-limited" — Your tier's per-minute throttle exceeded. Free tier is 5 tokens/min, paid tiers start at 20. Either wait or upgrade.

"npx -y @retailerapi/mcp hangs" — Usually a Node version issue. Confirm node --version returns 20 or higher. If it's older, upgrade via nvm install 20.

"Tool list is empty after restart" — The MCP server failed to start silently. Check the client's developer console for errors. Most common: malformed JSON in your config file (a stray comma).

What ships next

• compare_retailers tool for side-by-side comparison across all 7 supported retailers in one call (rolling out June 2026).
• watch_product tool that creates server-side price-drop alerts and notifies via webhook (rolling out July 2026).
• bulk_lookup tool for batched UPC requests, returning up to 1,000 products per call at a discounted token rate (rolling out August 2026).

Try it

Sign up free at app.retailerapi.com/signup, grab a key, and have the integration working in under 90 seconds. The MCP server source lives at github.com/retailerapi/mcp under MIT.