YardStock NZ Vehicle Listings

Live used-car stock on named New Zealand dealer yards. Search by make, model, price and city. Not Trade Me.

Documentation

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 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 10 dealer groups, roughly 6,000 live listings, Auckland-weighted.
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 <key>` or `X-Api-Key: <key>`
Site	https://yardstock.nz

Install

Claude Code

claude mcp add --transport http yardstock https://stock.yardstock.nz/mcp

With an API key:

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

Or manually: Settings → Connectors → Add custom connector, then paste

https://stock.yardstock.nz/mcp

Cursor

One-click:

→ Install in Cursor

Or add to ~/.cursor/mcp.json (global) or .cursor/mcp.json (per project):

{
  "mcpServers": {
    "yardstock": {
      "url": "https://stock.yardstock.nz/mcp"
    }
  }
}

The deep link above is the base64 of exactly that server config — verify it yourself:

printf '%s' '{"url":"https://stock.yardstock.nz/mcp"}' | base64
# eyJ1cmwiOiJodHRwczovL3N0b2NrLnlhcmRzdG9jay5uei9tY3AifQ==

VS Code

One-click:

→ Install in VS Code

Or from the CLI:

code --add-mcp '{"name":"yardstock","type":"http","url":"https://stock.yardstock.nz/mcp"}'

Or add to .vscode/mcp.json:

{
  "servers": {
    "yardstock": {
      "type": "http",
      "url": "https://stock.yardstock.nz/mcp"
    }
  }
}

Codex CLI

codex mcp add yardstock --url https://stock.yardstock.nz/mcp

Or in ~/.codex/config.toml:

[mcp_servers.yardstock]
url = "https://stock.yardstock.nz/mcp"

Windsurf

Add to ~/.codeium/windsurf/mcp_config.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 <key> 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 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:

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 10 named dealer groups' own yard websites, roughly 6,000 live listings, weighted towards Auckland.
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:

{
  "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.

Send it as either header:

Authorization: Bearer YOUR_KEY
X-Api-Key: YOUR_KEY

Repo contents

Path	What it is
`SKILL.md`	Agent skill — surface detection (MCP tools first, raw JSON-RPC fallback), argument docs, worked examples
`AGENTS.md`	Conventions for agents operating against this repo and API
`examples/curl.md`	Runnable JSON-RPC curl calls for all three tools, anonymous and keyed
`.claude-plugin/`	Claude Code plugin + self-hosted marketplace manifests
`context7.json`	Context7 indexing config

This repository contains documentation and client configuration only. No scraper, no pipeline, no dealer data.

YardStock NZ Vehicle Listings

Documentation