# CartScout MCP server

[![Tests](https://github.com/Veselin15/cartscout-mcp/actions/workflows/tests.yml/badge.svg)](https://github.com/Veselin15/cartscout-mcp/actions/workflows/tests.yml)

<!-- mcp-name: io.github.Veselin15/cartscout-mcp -->

Give Claude, Cursor or any MCP-capable AI agent **live product prices, stock, variants and deal
ratings** from online stores. Paste a product link into the chat and ask "is this a good price?",
"which of these three stores is cheapest and in stock?" or "does it come in size 10?".

Works with **Shopify, WooCommerce, Walmart and eBay** stores, with **Amazon in beta**. The data comes
from the [CartScout API](https://rapidapi.com/veselinveselinov06/api/cartscout-api), which handles
fetching, bot filters and parsing. [Try the API in your browser](https://api.vesflow.dev) first,
no sign-up needed.

## Tools

| Tool | What the agent gets | Uses |
|---|---|---|
| `get_product` | Price, list price and discount, stock, variants (sizes, colours) with their own price and stock, SKU / GTIN, rating, optional reviews and description | 1 extraction |
| `compare_products` | 2-10 pages ranked: cheapest, cheapest in stock, best rated, biggest discount, price spread, same product by GTIN | 1 extraction per URL, PRO plan or higher |
| `check_deal` | Deal rating of the current price against its recorded history, with average, lowest and highest price | 1 extraction (or none with `refresh: false`) |
| `get_price_history` | Recorded price and stock changes with current, lowest and highest price | No extractions |

Every tool is read-only and returns structured JSON with an output schema. Responses are trimmed
for agents: bulky parts such as all variants, reviews and the description are included only when
the agent asks for them.

## Setup

1. Subscribe to CartScout on RapidAPI. The **free plan includes 300 extractions a month**:
   [plans](https://rapidapi.com/veselinveselinov06/api/cartscout-api/pricing).
2. Copy your `X-RapidAPI-Key` from the RapidAPI dashboard.
3. Add the server to your client. It runs with [uv](https://docs.astral.sh/uv/), which installs it on
   first use.

### Claude Code

```bash
claude mcp add cartscout -e RAPIDAPI_KEY=your-rapidapi-key -- uvx --from git+https://github.com/Veselin15/cartscout-mcp cartscout-mcp
```

### Claude Desktop

Settings → Developer → Edit config, then add:

```json
{
  "mcpServers": {
    "cartscout": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/Veselin15/cartscout-mcp", "cartscout-mcp"],
      "env": { "RAPIDAPI_KEY": "your-rapidapi-key" }
    }
  }
}
```

### Cursor

Add the same `mcpServers` block to `~/.cursor/mcp.json` (all projects) or `.cursor/mcp.json` (one project).

## Example prompts

- "What does https://www.allbirds.com/products/mens-tree-runner-nz-ochre cost, and is size 10 in stock?"
- "Is $79 a good price for this air fryer? https://www.walmart.com/ip/844320666"
- "Compare these three listings and tell me the cheapest one I can buy today: …"
- "Show me how the price of this product changed over the last two weeks."

CartScout reads product pages; it does not search stores. Give the agent product URLs, or let it find
them with a web search tool first.

## Configuration

| Variable | Default | Purpose |
|---|---|---|
| `RAPIDAPI_KEY` | required | Your RapidAPI key |
| `CARTSCOUT_RAPIDAPI_HOST` | `cartscout-api.p.rapidapi.com` | RapidAPI host of the API |
| `CARTSCOUT_API_URL`, `CARTSCOUT_API_KEY` | unset | Use a directly issued CartScout key instead of RapidAPI |

The server sends only the product URLs your agent asks about to the CartScout API. Without a key
it still starts and lists its tools (handy for MCP inspectors); each tool call then explains how to
add `RAPIDAPI_KEY`.

### Docker

```bash
docker build -t cartscout-mcp .
docker run -i --rm -e RAPIDAPI_KEY=your-rapidapi-key cartscout-mcp
```

### HTTP transport

`cartscout-mcp --transport streamable-http --port 8000` serves the tools at
`http://127.0.0.1:8000/mcp`. Every client connected to it uses the key from the environment, so keep
it on a private address.

## Good to know

- Prices follow each store's own region and currency.
- Results can be cached for up to 60 minutes (`cached: true`).
- Price history and deal ratings build up as products are read. A product seen for the first time
  has little history to compare against.
- History range depends on the plan: 14 days on the free plan, up to 365 days on MEGA.
- When a store blocks a request, the tool returns an error explaining it, and the failed request is
  not billed.

## Development

```bash
uv sync
uv run pytest
```

## License

MIT