NEWOPEN SOURCEMCP-READY

ShoppingScraper CLI — every endpoint, one binary

ssc is the official command-line tool for the ShoppingScraper API. Scrape Amazon, Google Shopping, Bol.com, and Coolblue from your terminal — or wire it into Claude Desktop, Cursor, and Claude Code as a native MCP tool.

Get an API keyView on GitHub
Install
# Run without installing — zero setup
npx -y @shoppingscraper/cli credits

# With your API key
SSC_API_KEY=sk_live_... npx -y @shoppingscraper/cli \
  offers --site amazon.de --ean 0190198001281 --pretty

Why ssc

Built for agents, friendly for humans

The same retry, error, and credit-tracking glue you would write yourself — but solved once, versioned, and shipped behind a stable contract.

Every endpoint, one binary

credits, offers, info, buybox, match, search, page, variants, reviews — every ShoppingScraper API endpoint exposed as a sub-command with consistent flags.

MCP server out of the box

ssc mcp serve runs a stdio MCP server so Claude Desktop, Cursor, and Claude Code call your shopping data directly. Tool schemas auto-derived from zod.

Bulk + streaming

Pipe EANs from a file or stdin. Each request streams as an NDJSON envelope on stdout — fan out across thousands of products, jittered and concurrency-limited.

Spend caps that stick

ssc batch refuses to run without --max-spend-credits. Server-side caps on your API key are the real backstop — agents cannot spend past them.

Quick start

From zero to scraped offer in 60 seconds

Get an API key at app.shoppingscraper.com, drop it into your shell, and you are scraping.

  1. 1

    Install

    Use npx for one-off calls, or npm install -g for daily use.

  2. 2

    Set your API key

    Drop SSC_API_KEY into your shell rc, or use a per-project .env.

  3. 3

    Run a command

    Every endpoint is a sub-command. Output is one JSON line by default; add --pretty for humans.

  4. 4

    Pipe to jq, NDJSON to anything

    Stable envelope means jq '.result', awk on .meta.credits_remaining, or stream into Postgres.

Quick start
# 1. Set your API key
export SSC_API_KEY="sk_live_..."

# 2. Verify
ssc credits

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

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

# 5. Pipe to jq
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

Reference

Every command, every credit cost

Same endpoints as the REST API, exposed as predictable sub-commands. Credits debit per successful call; failed calls are not charged.

CommandWhat it doesCredits
ssc creditsShow remaining credits + plan info0
ssc historyRecent API calls for this key0
ssc offers --site --eanAll seller offers for an EAN1
ssc info --site --eanProduct title, brand, images, specs1
ssc buybox --site --eanCurrent buy-box winner + price1
ssc match --site --eanEAN → marketplace SKU/URL1 / 4
ssc search --country --keywordGoogle Shopping keyword search1
ssc page --urlStructured data from any product URL1
ssc variants --site --skuVariants for a Google Shopping SKU6
ssc reviews --site --skuReviews + rating distribution1
ssc batch <cmd> --inputFan out a command (NDJSON output)n × cost
ssc tools [--json-schema]List every command (agent introspection)0
ssc mcp serveRun an MCP server over stdio0

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

For AI agents

Native MCP server — Claude, Cursor, Code

ssc mcp serve runs a stdio Model Context Protocol server that exposes every command as a callable tool. Tool input schemas are auto-derived from the same zod schemas the CLI uses, so agents and humans see the identical contract.

Claude Desktop config
{
  "mcpServers": {
    "shoppingscraper": {
      "command": "npx",
      "args": ["-y", "@shoppingscraper/cli", "mcp", "serve"],
      "env": {
        "SSC_API_KEY": "sk_live_..."
      }
    }
  }
}

What your agent gets

  • ssc_credits, ssc_offers, ssc_info, ssc_buybox — every endpoint as a tool
  • Schemas auto-derived from zod — agent sees real types, not free-text
  • requiresConfirmation on high-cost tools (variants, deep-search match, batch)
  • Server-side credit caps remain the real backstop — annotations are advisory
  • Stable envelope: result is always the endpoint payload, error is a typed code

Authentication

Three ways to pass your key — pick one and forget

Resolution order is deterministic. Avoid the flag in shared shells — it lands in history. The CLI redacts the key from every log line, error envelope, and request id.

  1. 1.
    --api-key <key>

    Highest priority. Avoid in interactive shells.

  2. 2.
    SSC_API_KEY env var

    Recommended. Drop into shell rc or .env.

  3. 3.
    ~/.config/ssc/config.json

    {"api_key": "..."} — chmod 0600 recommended.

Spend caps

Three layers — only one of them matters

If your agent goes rogue, the only thing that actually saves your bill is the server-side cap. The other two are early-warning systems.

  1. Server-side (strongest)

    ShoppingScraper API enforces max_credits_per_call and per-key daily caps. HTTP 402 if exceeded. Cannot be bypassed.

  2. Client mandatory

    ssc batch refuses to run without --max-spend-credits N.

  3. Client advisory

    Global --max-spend-credits (default 100) and MCP requiresConfirmation annotations.

Library mode

Same package, importable

The CLI is a binary and a TypeScript library. Skip the subprocess, get typed results, keep retry and credit handling.

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();

Source code

MIT-licensed, TypeScript, on GitHub. Issues, PRs, and SECURITY.md welcome.

ShoppingResult/shoppingscraper-cli

npm package

@shoppingscraper/cli on npm. Installs the ssc binary.

npm install -g @shoppingscraper/cli

REST API docs

The underlying HTTP API the CLI calls. Same endpoints, raw JSON, every parameter.

app.shoppingscraper.com/apiguide

Frequently Asked Questions

What is the ShoppingScraper CLI?+

ssc is the official command-line tool for the ShoppingScraper API. It exposes every endpoint — offers, info, buybox, match, search, variants, reviews — as a sub-command, emits a stable JSON envelope on stdout, and ships with an MCP server mode for Claude Desktop, Cursor, and Claude Code. It is open source under MIT.

How do I install it?+

Either run npx -y @shoppingscraper/cli credits to use it without installing, or install globally with npm install -g @shoppingscraper/cli. A Homebrew tap (brew install ShoppingResult/tap/ssc) is in the works.

Where does the CLI store my API key?+

Resolution order: --api-key flag (avoid — lands in shell history), SSC_API_KEY environment variable (recommended), or ~/.config/ssc/config.json with mode 0600. The key is sent as a query-string parameter and redacted from logs and error envelopes.

Can I use it with Claude Desktop or Cursor?+

Yes. Run ssc mcp serve to start a stdio MCP server. Add it to claude_desktop_config.json (or any MCP-compatible host) with command: npx, args: ['-y', '@shoppingscraper/cli', 'mcp', 'serve'], and SSC_API_KEY in env. Every CLI command becomes a callable MCP tool — ssc_offers, ssc_buybox, ssc_match, etc.

How do spend caps work?+

Three layers. Server-side: the ShoppingScraper API enforces max_credits_per_call and per-key daily caps — cannot be bypassed. Client mandatory: ssc batch refuses to run without --max-spend-credits N. Client advisory: a global --max-spend-credits flag (default 100) plus MCP requiresConfirmation annotations on high-cost tools.

What does the JSON envelope look like?+

Every command emits one JSON object: { _v: 1, ok: true, command: 'offers', result: {...}, error: null, meta: { credits_remaining, duration_ms, request_id } }. On failure, ok: false and 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, 2 auth, 3 rate-limit, 4 upstream, 5 network, 6 spend-cap.

Is the source code available?+

Yes. The CLI is open source on GitHub at github.com/ShoppingResult/shoppingscraper-cli under the MIT license. The same package can be imported as a library: import { HttpClient, endpoints, resolveConfig } from '@shoppingscraper/cli'.

Which marketplaces does it cover?+

Anything the ShoppingScraper API covers — Amazon (16 domains), Google Shopping, bol.com, Coolblue, IKEA, Lidl, Albert Heijn, LEGO, Decathlon, H&M, fonQ, HORNBACH, and the generic Webshop scraper. Pass --site amazon.de, --site bol.com, --site shopping.google.nl, etc.

Get the CLI in your hands

Free trial includes 100 API credits. Drop them into ssc and you are scraping in 60 seconds.

Get an API keyView on GitHub