ssc — ShoppingScraper CLI

Price scraper CLI for Amazon, Google Shopping, Bol.com, and Coolblue. Scrape prices, offers, buy-box winners, variants, and reviews from your terminal — or wire it into Claude Desktop / Cursor / Claude Code as a native MCP tool.

🌐 Website: shoppingscraper.com · 🔑 Get an API key: app.shoppingscraper.com · 📖 API docs: apiguide

Agent-friendly command-line tool for the ShoppingScraper API by shoppingscraper.com. Stable JSON envelope on every command, MCP server mode for Claude Desktop / Cursor / Code, ships with a SKILL.md so any LLM picks it up without schema wrapping.

Why

You're an AI agent (or a developer building one) and you need product data — prices, offers, buy-box winners, variants, reviews — from Google Shopping, Amazon, Bol.com, or Coolblue. Today you're hitting the raw HTTP API and writing the same retry/error/credit-tracking glue every time. ssc is that glue, in one binary, with a stable contract.

Use cases:

• Price monitoring CLI — fan out across thousands of EANs from cron / GitHub Actions / your CI.
• E-commerce scraping — match an EAN to a marketplace SKU, pull every offer, watch the buy-box.
• AI agents — give Claude/Cursor live marketplace data via the built-in MCP server.
• Bulk price scraping — ssc batch reads EANs from stdin, streams NDJSON envelopes.

Install

# Run without installing
npx -y @shoppingscraper/cli credits

# Global install
npm install -g @shoppingscraper/cli

# Or via Homebrew (post-launch)
brew install ShoppingResult/tap/ssc

Quick start

# 1. Set your API key (get one at https://app.shoppingscraper.com)
export SSC_API_KEY="<your-key>"

# 2. Verify
ssc credits
# → {"_v":1,"ok":true,"command":"credits","result":{...},"meta":{...}}

# 3. Get offers for an EAN on a marketplace
ssc offers --site amazon.de --ean 0190198001281

# 4. Pretty output for humans
ssc buybox --site bol.com --ean 0190198001281 --pretty

# 5. Pipe-friendly: get just the result payload
ssc info --site shopping.google.nl --ean 0190198001281 | jq '.result'

# 6. Bulk: 500 EANs from a file, capped at 500 credits
ssc batch offers --input eans.txt --site amazon.de --max-spend-credits 500

Commands

Command	What it does	Credits
ssc credits	Show remaining credits + plan info	0
ssc history	Recent API calls for this key	0
ssc offers --site --ean	All seller offers for an EAN	1
ssc info --site --ean	Product title, brand, images, specs	1
ssc buybox --site --ean	Current buy-box winner + price	1
ssc match --site --ean [--deepsearch]	EAN → marketplace SKU/URL	1 / 4
ssc search --country --keyword	Google Shopping search	1
ssc page --url	Structured data from any product URL	1
ssc variants --site --sku	Variants for a Google Shopping SKU ⚠	6
ssc reviews --site --sku	Reviews + rating distribution	1
ssc batch <cmd> --input	Fan out a command (NDJSON output)	n × cost
ssc tools [--json-schema]	List every command (for agent introspection)	0
ssc mcp serve	MCP server over stdio	0

⚠ = high-cost, gets requiresConfirmation: true in MCP tool annotations.

Bulk / streaming

Every scraping command accepts --input <file|->. Reads one EAN/SKU per line, fans out with the configured concurrency (default 5), jitters each request 200–800ms, streams NDJSON envelopes. Lines beginning with # are comments.

# From a file
ssc offers --input eans.txt --site amazon.de --max-spend-credits 500

# From stdin
cat eans.txt | ssc info --site bol.com --input - --max-spend-credits 100

# `ssc batch` is sugar with a mandatory cap
ssc batch buybox --input eans.txt --site amazon.de --max-spend-credits 200

ssc batch requires --max-spend-credits N — there is no default. This is deliberate: agents bypassing this flag is the highest-blast-radius mistake an MCP-driven workflow can make.

Output format

Every command emits a stable JSON envelope on stdout (one line for batch/streaming):

{
  "_v": 1,
  "ok": true,
  "command": "offers",
  "result": { /* endpoint payload */ },
  "error": null,
  "meta": {
    "credits_remaining": 12483,
    "duration_ms": 412,
    "request_id": "ssc_01a2b3c4d5e6f708"
  }
}

On failure: ok: false, result: null, error.code is one of AUTH_MISSING | AUTH_INVALID | RATE_LIMITED | UPSTREAM_ERROR | NETWORK_ERROR | SPEND_CAP_EXCEEDED | NOT_FOUND | INVALID_RESPONSE | USER_ERROR.

Exit codes:

• 0 ok · 1 user error · 2 auth · 3 rate-limit · 4 upstream · 5 network · 6 spend-cap exceeded.

Pass --pretty for a human-readable view; --quiet to suppress stdout (only the exit code matters).

Authentication

Resolution order:

1. --api-key <key> flag (avoid — lands in shell history)
2. SSC_API_KEY environment variable (recommended)
3. ~/.config/ssc/config.json with {"api_key": "..."} (mode 0600 recommended)

The CLI sends the key as a query-string parameter (?api_key=...) to match the deployed ShoppingScraper API contract. All URLs are redacted before they appear in logs, error envelopes, or meta.request_id.

MCP — Model Context Protocol

ssc mcp serve

Run as a stdio MCP server, exposing every command as a tool (ssc_offers, ssc_info, ssc_buybox, …). Tool input schemas are auto-derived from the same zod schemas the CLI uses, so agents and humans see the same contract.

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "shoppingscraper": {
      "command": "npx",
      "args": ["-y", "@shoppingscraper/cli", "mcp", "serve"],
      "env": { "SSC_API_KEY": "<your-key>" }
    }
  }
}

Cursor / Claude Code

Same shape — point any MCP-compatible host at npx -y @shoppingscraper/cli mcp serve with SSC_API_KEY in the env.

Tool annotations

High-cost tools (ssc_variants, ssc_match with --deepsearch, anything bulk) carry requiresConfirmation: true. This annotation is advisory — well-behaved hosts prompt before invoking; hostile or headless clients ignore it. The real spend-cap brake is --max-spend-credits and the server-side cap on your ShoppingScraper API plan.

Spend-cap defenses

Three layers, in order of strength:

1. Server-side (strongest) — the ShoppingScraper API enforces max_credits_per_call and per-key daily caps. Returns HTTP 402 with credits_required. Cannot be bypassed by anything.
2. Client-side mandatory — ssc batch refuses to run without --max-spend-credits N.
3. Client-side advisory — global --max-spend-credits (default 100) on every command; per-tool soft caps; MCP requiresConfirmation annotations.

To disable client-side caps for a power-user workflow:

ssc batch offers --input eans.txt --site amazon.de --max-spend-credits none

Programmatic use

import { HttpClient, endpoints, resolveConfig } from "@shoppingscraper/cli";

const cfg = resolveConfig();
const client = new HttpClient({
  apiKey: cfg.apiKey,
  baseUrl: cfg.baseUrl,
  appBaseUrl: cfg.appBaseUrl,
  timeoutMs: 30_000,
  retries: 2,
});
const r = await endpoints.offers(client, { site: "amazon.de", ean: "0190198001281" });
console.log(r.creditsRemaining, r.data);
await client.close();

Development

npm install
npm run typecheck
npm test
npm run build
node dist/cli.js --help

Security

See SECURITY.md. Found a vulnerability? Email security@shoppingscraper.com. Please do not open a public issue.

About ShoppingScraper

ssc is built and maintained by ShoppingScraper — the e-commerce price-scraping API for Amazon, Google Shopping, Bol.com, Coolblue, and 30+ other marketplaces. EAN-precise, real-time, and built for AI agents.

• 🌐 Website: shoppingscraper.com
• 🔑 Get an API key: app.shoppingscraper.com
• 📖 API docs: app.shoppingscraper.com/apiguide
• 📨 Contact: hello@shoppingscraper.com

License

MIT — © ShoppingScraper