carsales-mcp

An MCP server that lets an AI assistant search carsales.com.au — Australia's largest car marketplace — for used and new cars.

Built for Claude Desktop, Claude Code, Cursor, and any MCP-compatible client.

Tools

search_cars

Search for cars. Filters are applied as carsales URL facets where supported, and price / year / odometer are filtered in-memory from the listing cards (these have no simple URL param).

get_listing_details

Get full details for one listing by listingId (e.g. OAG-AD-26099426) or full url. Falls back to summary card data if the detail page is bot-blocked.

Holistic view. The tools surface the full listing picture for the model:

• get_listing_details / fetch return the price (drive-away and ex-govt-charges), price indicator (FAIR/GOOD/GOOD/ GREAT PRICE), year, odometer, transmission, fuel, body, engine, seller + state, the feature/spec bullet list, the description, and the photo gallery.

• Set includeImages: true (default for get_listing_details/fetch) and the actual photos are downloaded and returned as MCP image blocks, so a multimodal model can literally see the car. search has includeImages too (off by default) to attach each result's thumbnail.

• search returns each result's image URL in its JSON even when images aren't embedded.

Setup

1. Install Playwright's browser

npm install -g carsales-mcp      # OR clone + npm install
npx playwright install chromium   # downloads the full Chromium build (needed!)

The full Chromium build (channel: 'chromium') is required — the headless shell is fingerprinted and blocked by DataDome. On Linux you may also need system libraries: npx playwright install-deps chromium (or your distro's equivalents of libnss3, libnspr4, libasound2).

2. Add to your MCP client

Claude Desktop — ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "carsales": {
      "command": "npx",
      "args": ["-y", "carsales-mcp"]
    }
  }
}

Claude Code — ~/.claude/.mcp.json:

{
  "mcpServers": {
    "carsales": {
      "command": "npx",
      "args": ["-y", "carsales-mcp"]
    }
  }
}

3. (Optional) Proxy / anti-bot tuning

carsales.com.au is behind DataDome. The server is built to survive this:

Camoufox is the default engine. Camoufox is a Firefox-based anti-detect browser with a much harder-to-fingerprint profile than Chromium. The Camoufox binary is downloaded automatically on first launch (it runs npx camoufox-js fetch for you — no manual step), and if Camoufox ever fails to launch, the server transparently falls back to Chromium. Force Chromium with CARS_ENGINE=chromium.

API + scraping balance (mirrors secondhand-mcp). If you have a Carapis API key, set CARAPIS_API_KEY and search_cars will pull clean structured JSON from their carsales.com.au endpoint (no bot challenges). If the key is absent or the call fails, it falls back to the browser scraper. This is the same official-API-where-possible / scrape-where-not strategy secondhand-mcp uses for eBay vs Depad/Poshmark.

Proxy. DataDome blocks primarily by IP reputation, so a (residential) proxy is the most reliable fix. Set CARS_PROXY to a single proxy, or a comma-separated list to rotate across proxies per request (combined with the retry logic below):

"env": {
  "CARS_PROXY": "http://user:pass@proxy1:8000,http://user:pass@proxy2:8000",
  "CARAPIS_API_KEY": "your-key"
}

Other tuning env vars:

"env": { "CARS_PROXY": "http://127.0.0.1:8899" }

Notes & limits

• DataDome may occasionally challenge; if a search returns nothing, just retry.

• Respect carsales' terms of service and avoid hammering with very high page counts.

• No official carsales API is used — this scrapes the public site via a real browser.

License

MIT