# chocodata-mcp

MCP server for the [Chocodata](https://chocodata.com) web scraping API. Gives Claude, Cursor, Cline, Continue and any other MCP-compatible client tools to scrape the web, so an agent can pull live product prices, search results and social profiles without you writing glue code.

Runs over stdio. Node 18+.

## Setup

Add it to your client's MCP config. It runs on demand via `npx`, so there is no global install and no version drift:

```json
{
  "mcpServers": {
    "chocodata": {
      "command": "npx",
      "args": ["-y", "chocodata-mcp"],
      "env": { "CHOCODATA_API_KEY": "asa_live_YOUR_KEY" }
    }
  }
}
```

Get a key at [chocodata.com](https://chocodata.com). The free tier is 1,000 requests, one time, no card.

**Claude Desktop:** `claude_desktop_config.json`.
**Cursor:** Settings, then MCP, then Add.
Restart the client after editing, then ask it something like *"what does this Amazon ASIN cost in Germany?"*

## Tools

| Tool | What it does |
|---|---|
| `amazon_product` | One product by ASIN/ISBN (`query`) or `url`. Prices localise to `domain`. |
| `amazon_search` | Amazon search results. |
| `walmart_product` | One item by `url` or `id`. |
| `walmart_search` | Walmart search results. |
| `ebay_product` | One listing with ISO currency, stock status, quantity sold/available. |
| `ebay_search` | eBay search results. |
| `bing_search` | Web results. Good for grounding an answer in current sources. |
| `bing_images` | Image results with source pages. SafeSearch strict by default. |
| `tiktok_profile` | Public profile with follower/like/video counts. |
| `youtube_video` | Title, exact view and like counts, duration, channel. |
| `instagram_profile` | Public profile: followers, bio, post count, verified. |
| `scrape` | **Any** of the 499 endpoints, for anything above not covered. |

Parameters follow the API's real contract rather than a uniform invention: `amazon_product` takes `query`, `walmart_product` takes `url` or `id`, and the Bing tools take `q`. Each tool's schema documents its own parameters, so the agent picks the right ones.

## The generic tool

`scrape` reaches everything else in the catalog:

```
target:   "reddit"
resource: "post"
params:   { "post_id": "627akk", "subreddit": "askscience" }
```

Browse every target and its parameters at [chocodata.com/scraper-api](https://chocodata.com/scraper-api).

## Errors

Failures come back as readable tool errors rather than stack traces, and say whether retrying will help:

```
Chocodata error 404 item_not_found: That TikTok handle does not resolve:
it has been deleted, renamed, or is unavailable in this region.
Request id: d2f460a7-...
```

**You are only charged on a 2xx.** Errors cost no credits. Retryable failures (429, 5xx, network) are retried automatically with backoff before the agent ever sees them.

## Rate limits

120 requests per key per 60 seconds, plus a per-plan concurrency ceiling. An agent looping over many items can hit that; the server backs off and retries rather than failing the whole tool call.

## License

MIT