@cartpie/mcp

MCP server for Cartpie — clean, normalized product data from any retailer URL, for your agent. A raw product page is 50–500KB of HTML; Cartpie returns a ~1–2KB structured object.

Tools

| Tool | Args | Returns | |------|------|---------| | extract_product | url, format?, freshness? | normalized product JSON + credits charged | | extract_products | urls[] (≤20) | one result per URL, each with its credits | | find_offers | gtin | same product across retailers, cheapest first | | get_usage | — | current-period credit usage + remaining allowance | | get_pricing | — | public credit pricing table (works without a key) |

Setup

Get an API key at cartpie.com, then:

Claude Desktop / Cursor (mcp.json / config)

{
  "mcpServers": {
    "cartpie": {
      "command": "npx",
      "args": ["-y", "@cartpie/mcp"],
      "env": { "CARTPIE_API_KEY": "cp_live_…" }
    }
  }
}

Run directly

CARTPIE_API_KEY=cp_live_… npx @cartpie/mcp

Credit model

Cartpie meters in credits. Credits are charged by how a page was served — the cheapest path that succeeds — not by a fixed per-retailer price, so the same URL can cost different amounts on different requests. Cache hits and failed extractions are free. Each extract_product / extract_products result reports the exact charge in meta.credits (also surfaced as credits).

• get_pricing returns the credit table by tier (direct fetch, residential proxy, JS render, premium proxy, unlocker). No key required.
• get_usage returns credits_remaining for the current period.

Async extraction

Most extractions are synchronous. A hard, bot-protected page can escalate to an async job (HTTP 202). The server polls the result automatically with bounded backoff (defaults: ~6 attempts, ~45s cap). If it's still processing when the window closes, the tool returns { "status": "processing", "page_id": … } — the result is cached, so a quick retry returns it.

Env

• CARTPIE_API_KEY — your key. Required for extract_product, extract_products, find_offers, get_usage. Not needed for get_pricing.
• CARTPIE_API_BASE — defaults to https://api.cartpie.com. For local development against a self-hosted API set http://localhost:8080.
• CARTPIE_POLL_MAX_ATTEMPTS — async-job poll attempts after a 202 (default 6).
• CARTPIE_POLL_TOTAL_CAP_MS — hard cap on total polling time, ms (default 45000).
• CARTPIE_POLL_BASE_DELAY_MS — base delay between polls, ms (default 2000).

License

MIT.