YardStock — NZ Vehicle Listings MCP
Live used-car stock on named New Zealand dealer yards — searchable by make, model, price and city, straight from your agent. Not Trade Me.
Works with Claude Code, Claude Desktop, Cursor, VS Code, Codex, Windsurf, ChatGPT (developer mode), Perplexity and any MCP client.
---
## What this is
YardStock is a hosted [Model Context Protocol](https://modelcontextprotocol.io) server that exposes **live used-vehicle stock scraped from NZ dealer groups' own yard websites**.
- **Not** Trade Me. **Not** AutoTrader. **Not** a national roster of every car for sale in New Zealand.
- Currently **200+ dealer yards**, roughly **30,000 live listings**, **New Zealand-wide**. The `coverage` tool always states the exact live figure.
- Every answer carries a coverage block so an agent can state what it did *not* look at.
| | |
|---|---|
| **MCP endpoint** | `https://stock.yardstock.nz/mcp` (Streamable HTTP, JSON-RPC over POST) |
| **Health check** | `https://stock.yardstock.nz/health` → `{"ok": true, "service": "nz-yard-stock"}` (open, no auth) |
| **Registry name** | `nz.yardstock/nz-car-listings` v1.0.0 |
| **Auth** | `Authorization: Bearer ` or `X-Api-Key: ` |
| **Site** | |
---
## Install
### Claude Code
```bash
claude mcp add --transport http yardstock https://stock.yardstock.nz/mcp
```
With an API key:
```bash
claude mcp add --transport http yardstock https://stock.yardstock.nz/mcp \
--header "Authorization: Bearer YOUR_KEY"
```
### Claude Desktop / Claude web (custom connector)
One-click:
**[→ Add YardStock to Claude](https://claude.ai/customize/connectors?modal=add-custom-connector&connectorName=YardStock&connectorUrl=https%3A%2F%2Fstock.yardstock.nz%2Fmcp)**
Or manually: **Settings → Connectors → Add custom connector**, then paste
```
https://stock.yardstock.nz/mcp
```
### Cursor
One-click:
**[→ Install in Cursor](cursor://anysphere.cursor-deeplink/mcp/install?name=yardstock&config=eyJ1cmwiOiJodHRwczovL3N0b2NrLnlhcmRzdG9jay5uei9tY3AifQ%3D%3D)**
Or add to `~/.cursor/mcp.json` (global) or `.cursor/mcp.json` (per project):
```json
{
"mcpServers": {
"yardstock": {
"url": "https://stock.yardstock.nz/mcp"
}
}
}
```
The deep link above is the base64 of exactly that server config — verify it yourself:
```bash
printf '%s' '{"url":"https://stock.yardstock.nz/mcp"}' | base64
# eyJ1cmwiOiJodHRwczovL3N0b2NrLnlhcmRzdG9jay5uei9tY3AifQ==
```
### VS Code
One-click:
**[→ Install in VS Code](https://insiders.vscode.dev/redirect/mcp/install?name=yardstock&config=%7B%22type%22%3A%22http%22%2C%22url%22%3A%22https%3A%2F%2Fstock.yardstock.nz%2Fmcp%22%7D)**
Or from the CLI:
```bash
code --add-mcp '{"name":"yardstock","type":"http","url":"https://stock.yardstock.nz/mcp"}'
```
Or add to `.vscode/mcp.json`:
```json
{
"servers": {
"yardstock": {
"type": "http",
"url": "https://stock.yardstock.nz/mcp"
}
}
}
```
### Codex CLI
```bash
codex mcp add yardstock --url https://stock.yardstock.nz/mcp
```
Or in `~/.codex/config.toml`:
```toml
[mcp_servers.yardstock]
url = "https://stock.yardstock.nz/mcp"
```
### Windsurf
Add to `~/.codeium/windsurf/mcp_config.json`:
```json
{
"mcpServers": {
"yardstock": {
"serverUrl": "https://stock.yardstock.nz/mcp"
}
}
}
```
### ChatGPT (developer mode)
**Settings → Connectors → Advanced → Developer mode**, then **Create** a connector with:
- **Name:** `YardStock`
- **MCP server URL:** `https://stock.yardstock.nz/mcp`
- **Authentication:** No authentication (free tier) or a custom `Authorization: Bearer ` header for full access.
### Perplexity
**Settings → Connectors → Add connector → Custom**, transport **HTTP (Streamable)**, URL:
```
https://stock.yardstock.nz/mcp
```
### Any other MCP client
Point it at `https://stock.yardstock.nz/mcp` with transport **Streamable HTTP**. Nothing to install, nothing to run locally. See [`examples/curl.md`](examples/curl.md) for raw JSON-RPC.
### As a Claude Code plugin
This repo also ships a self-hosted plugin marketplace, which installs the connector and the bundled agent skill together:
```bash
claude plugin marketplace add aaronwaddington-arch/yardstock-mcp
claude plugin install yardstock@yardstock
```
---
## Tools
| Tool | Arguments | Returns |
|---|---|---|
| `coverage` | none | `groups[{legal_name, listing_count, cities[]}]` — exactly which dealer groups are in scope right now |
| `search_stock` | `make`, `model`, `year_min`, `year_max`, `price_min_nzd`, `price_max_nzd`, `city`, `fuel`, `limit` (≤50, default 20) | results sorted **price ascending**: `{source_url, year, make, model, price_nzd, odometer_km, fuel, yard_label, city, trader_name, last_seen}` |
| `get_listing` | `source_url` | one listing, plus `vin` / `plate` where stored (keyed access only) |
All arguments to `search_stock` are optional — omit them all and you get the cheapest live stock across every covered yard.
---
## Example utterances
Ask your agent, in plain language:
- "Find me a 2019 Hilux under $35k in Auckland."
- "Which NZ dealer groups do you actually have live stock for?"
- "Show me every diesel ute under $30,000, cheapest first."
- "Any RAV4 with under 80,000 km on the clock?"
- "What's the price spread on a Ford Ranger across the yards you cover?"
- "List Toyota Corollas from 2018 or newer under $25k."
- "Compare Mazda CX-5 pricing between the Auckland yards and everywhere else you cover."
- "Pull the full detail for this listing — odometer, fuel, which yard it's sitting on."
- "How fresh is this? When was each of these last seen on the yard's website?"
- "I've got $18,000 — what's the newest low-kilometre hybrid you can actually see right now?"
The agent should answer with results **and** with what it could not see. That is the point of the product.
---
## Coverage honesty
YardStock is deliberately narrow, and the API is built so an agent cannot pretend otherwise.
- Data comes from **200+ named dealer yards' own websites**, roughly **30,000 live listings**, **New Zealand-wide**.
- It is **not** Trade Me, **not** AutoTrader, and **not** a complete picture of the New Zealand used-car market. A car absent from YardStock is not a car that does not exist.
- Every response carries a coverage block:
```json
{
"groups_with_stock": 10,
"live_listings": 6000,
"last_seen_max": "2026-08-25T09:00:00Z",
"not_included": ["Trade Me", "AutoTrader", "private sellers", "dealer groups not listed by coverage()"]
}
```
- **Agents must never invent stock for uncovered groups.** If a user asks about a dealer group that `coverage()` does not list, the correct answer is "that group is not in YardStock's coverage", not a guess.
- `last_seen` on each listing is the freshness signal. A listing that has not been seen recently may already be sold — say so rather than presenting it as certainly available.
---
## Get a key
The free tier is anonymous: connect with no credentials, list tools, and run capped searches (`limit` 5, no VIN or plate).
Full access — the full `limit` up to 50, and `vin`/`plate` on `get_listing` — needs an API key. **Keys are issued manually at the moment; request one via [yardstock.nz](https://yardstock.nz).**
Send it as either header:
```
Authorization: Bearer YOUR_KEY
X-Api-Key: YOUR_KEY
```
---
## Repo contents
| Path | What it is |
|---|---|
| [`SKILL.md`](SKILL.md) | Agent skill — surface detection (MCP tools first, raw JSON-RPC fallback), argument docs, worked examples |
| [`AGENTS.md`](AGENTS.md) | Conventions for agents operating against this repo and API |
| [`examples/curl.md`](examples/curl.md) | Runnable JSON-RPC curl calls for all three tools, anonymous and keyed |
| [`.claude-plugin/`](.claude-plugin) | Claude Code plugin + self-hosted marketplace manifests |
| [`context7.json`](context7.json) | Context7 indexing config |
This repository contains documentation and client configuration only. No scraper, no pipeline, no dealer data.
---
## License
[MIT](LICENSE) © 2026 Aaron Waddington