The full upstream README, mirrored here for reference. Install config, tool schemas, adoption signals, and an original overview live on the Carsensor Price Range MCP Server for AI Agents listing page.
If you're building an AI agent, chatbot, or app that needs to answer "is this used car's asking price
fair?" — not a guess, but a number grounded in real market data — this MCP server gives you exactly that
in a single tool call. resolvePriceRange(carModel, year) returns a market-price range (min / max / median)
computed live from carsensor.net's own official price-by-model-year market statistics — the same data
carsensor itself publishes on its 相場(market price) pages, turned into a structured, ready-to-use number
instead of a page you'd have to read and interpret yourself.
What you get:
resolvePriceRange, taking just a car model name and a year — no API keys to manage for the
underlying data source, no HTML to parse yourselfpriceRangeYen: { min, max, median } plus sampleSize (how many real carsensor listings the estimate is
based on) and confidence (normal / low — honestly downgraded, not hidden, when the year can't be
fully verified against carsensor's own data; see "Known limitations")Pay-per-event pricing — see "Pricing" below. Full input/output details, setup, and technical design are further down this page.
priceRangeYen is a statistical estimate derived from carsensor's own published price×model-year
aggregate data, not a guarantee of any individual vehicle's true value. It does not account for
condition, trim/grade differences, or mileage (see "Known limitations"). Always verify a specific
vehicle's price on carsensor.net itself before making any purchase or sale decision based on this data.carsensor-resale-value-scout Actor (which scores whole
lists of listings against the same underlying market data)Input (MCP tool call arguments):
| Parameter | Type | Required | Description |
|---|---|---|---|
carModel | string | Yes | Car model name, same free-text format as carsensor's own search (e.g. "プリウス", "N-BOX") |
year | integer | Yes | Model year, 4-digit (e.g. 2018) |
Output (success):
| Field | Type | Description |
|---|---|---|
priceRangeYen.min / .max / .median | integer (JPY) | Estimated market-price range for this model/year |
sampleSize | integer | Number of carsensor listings the estimate is aggregated from |
confidence | "normal" | "low" | "low" when the year only matches an open-ended bucket in carsensor's data (see "Known limitations") — a note field explains why when this happens |
cacheStatus | object | tier1/tier2 — whether this call hit cached data or made a fresh request to carsensor.net (informational only, does not affect price — see "Pricing") |
Output (model not found / no data for that year): { "ok": false, "reason": "no_code_resolved" | "no_matching_data", "message": "..." } — not charged (see "Pricing").
Claude Desktop / any MCP client config:
Calling it directly from your own app (Node.js, @modelcontextprotocol/sdk):
| Event | Price | Trigger |
|---|---|---|
Price range resolved (resolve-price-range-success) | $0.03 | Charged only when resolvePriceRange successfully returns a price range. Not charged when the car model can't be resolved or no matching year data exists |
Flat pricing regardless of whether the call hit cached data or triggered a fresh request to carsensor.net — see "How the price was set" below for the full reasoning, including why cache-tiered pricing was deliberately rejected.
$0.03 sits between this Actor family's base classification tier ($0.015, e.g. listing-extracted on our
carsensor-resale-value-scout Actor) and its heavier derived-signal tier ($0.045–$0.065, e.g.
value-score-computed) — reflecting that a price range is a computed market signal, not a raw data fetch,
while this tool's underlying infra cost (well under $0.001/call, most calls served from cache) leaves a
large margin either way.
Why cache hits and misses are priced the same: the value delivered — priceRangeYen, sampleSize,
confidence — is identical either way; caching is purely an internal performance/cost optimization, not a
difference in what you get. Pricing it differently would also create a perverse incentive to shorten the
cache TTL (more misses = more revenue), which runs directly against this tool's own design goal of
minimizing load on carsensor.net.
Uses carsensor.net's own publicly-published 相場(market price) page for the resolved model
(/usedcar/souba/{makerCode}_S{modelCode}/), specifically its "price × model-year" cross-tabulation
(price bucket, year bucket, listing count per cell) — official aggregate data carsensor itself computes
from its own live inventory, not a third-party estimate.
median is a count-weighted average of each matching year-bucket's price-bucket midpointmin / max come from the actual price-bucket bounds of the matching cells (open-ended buckets, e.g.
"¥4,150,000 or more", are approximated with a ±15% heuristic — an empirical adjustment, not a
statistically derived one)| Tier | Key | Value | Storage | Expiry |
|---|---|---|---|---|
| 1 | Car model name | { makerCode, modelCode } | File-persisted | Unbounded (carsensor's model coding is effectively static) |
| 2 | {makerCode}_S{modelCode} | carsensor's price×model-year cells | File-persisted | 12 hours |
A cache hit on both tiers means zero HTTP requests to carsensor.net for that call. On the Apify-hosted version, this cache is scoped to a single Standby run/container instance — concurrent sessions can land on different container instances with independent caches, so the real-world hit rate on the hosted version may be lower than what a single long-running local process would see. A future version may move this to Apify's Key-Value Store (shared across runs) if this turns out to matter in practice.
Requests to carsensor.net are paced at a minimum 1000ms interval (1500ms by default) as a load-reduction
measure — the same floor used by our carsensor-resale-value-scout Actor. Every call is logged (model,
year, per-tier cache hit/miss, HTTP requests actually made, response time, outcome) for future monitoring —
not exposed to callers, used only for operating this Actor responsibly.
Why is confidence sometimes "low"?
carsensor's year axis has an open-ended bottom bucket in its own data (e.g. "2012 or earlier"). Any year at
or before that bound will match it, whether or not the model actually existed yet in that year — there's no
way to fully verify plausibility from this data alone, so confidence is honestly downgraded rather than
reported as certain. See the note field on such responses for the specific reason.
Why does my first call for a given model take a few seconds, but repeat calls are much faster? The first call for an unfamiliar model needs up to 3 real requests to carsensor.net (search → detail page → market-price page) to resolve which model this is. Once resolved, the model→code mapping is cached effectively permanently, and the price data itself is cached for 12 hours — so repeat calls for the same model are near-instant.
Does this cover mileage? Not yet — see "What can't it do."
How is this different from carsensor-resale-value-scout?
That Actor is a batch scraper: give it a search term, get back a list of live listings each scored against
this same market data. This Actor is the single-call, on-demand counterpart, built for AI agents and apps
that want one number for one model/year — not a list to scrape and process.
confidence cannot fully verify whether a queried year is plausible for a given model — see FAQ.carsensor-resale-value-scout's codebase, to keep the two independently-deployed Actors decoupled. A
carsensor.net markup change affecting one may require a matching fix in the other.