Content
# `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.
[](https://www.npmjs.com/package/@shoppingscraper/cli)
[](https://github.com/ShoppingResult/shoppingscraper-cli/actions/workflows/ci.yml)
[](./LICENSE)
**🌐 Website:** [shoppingscraper.com](https://shoppingscraper.com) · **🔑 Get an API key:** [app.shoppingscraper.com](https://app.shoppingscraper.com) · **📖 API docs:** [apiguide](https://app.shoppingscraper.com/apiguide)
Agent-friendly command-line tool for the [ShoppingScraper API](https://app.shoppingscraper.com/apiguide) by [shoppingscraper.com](https://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
```bash
# 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
```bash
# 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.
```bash
# 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):
```json
{
"_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
```bash
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`:
```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:
```bash
ssc batch offers --input eans.txt --site amazon.de --max-spend-credits none
```
## Programmatic use
```ts
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
```bash
npm install
npm run typecheck
npm test
npm run build
node dist/cli.js --help
```
## Security
See [SECURITY.md](./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](https://shoppingscraper.com)** — 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](https://shoppingscraper.com)**
- 🔑 Get an API key: **[app.shoppingscraper.com](https://app.shoppingscraper.com)**
- 📖 API docs: **[app.shoppingscraper.com/apiguide](https://app.shoppingscraper.com/apiguide)**
- 📨 Contact: hello@shoppingscraper.com
## License
MIT — © [ShoppingScraper](https://shoppingscraper.com)
