carsensor Price Range MCP Server for AI Agents

面向 AI Agent 的 carsensor 价格区间 MCP 服务

如果你正在构建一个 AI Agent、聊天机器人或应用，需要回答“这辆二手车的标价合理吗？”——不是凭猜测，而是根据真实市场数据得出一个数字——这个 MCP 服务只需一次工具调用就能提供答案。resolvePriceRange(carModel, year) 会返回市场价格区间（最低价 / 最高价 / 中位数），这些数据根据 carsensor.net 自有的官方车型和年份市场价格统计实时计算得出——也就是 carsensor 在其相场（市场价格）页面上发布的数据，并将其转换成结构化、可直接使用的数字，无需你自行阅读和解读网页。

你将获得：

• 一个工具 resolvePriceRange，只需传入车型名称和年份——无需管理底层数据源的 API 密钥，也无需自行解析 HTML
• priceRangeYen: { min, max, median }，以及 sampleSize（估算所依据的真实 carsensor 刊登数量）和 confidence（normal / low——当无法通过 carsensor 自有数据完全验证年份时，会如实降低置信度，不会隐瞒；详见“已知限制”）
• 通过 Apify Standby 模式全天候托管——无需自行运行服务。可将任意 MCP 客户端（Claude Desktop、Claude Code 或你自己的 Agent）直接连接到稳定的 HTTPS 端点，也可在自己应用的代码中将其作为普通的 Streamable HTTP MCP 服务调用

{
  "ok": true,
  "carModel": "プリウス",
  "year": 2018,
  "priceRangeYen": { "min": 750000, "max": 4772500, "median": 1573112 },
  "sampleSize": 412,
  "confidence": "normal",
  "disclaimer": "carsensor.net上の公開情報(相場ページの価格×年式集計)を基にした参考値です。個体差・装備差・実際の商談結果は反映されません。"
}

按调用事件付费——详见下文“定价”。完整的输入 / 输出详情、设置方法和技术设计见本页后续内容。

⚠️ 免责声明（请阅读）

• 此 Actor 会自动检索 carsensor.net 上公开提供的信息。你需自行负责如何检索和使用这些数据。
• 网站所有者的使用条款、robots.txt 或访问限制可能会在不另行通知的情况下发生变化，从而导致此 Actor 无法运行或意外改变其输出。
• **priceRangeYen 是根据 carsensor 自行发布的价格 × 车型年份汇总数据得出的统计估算值，并不保证等于任何单辆车的实际价值。**该估算不考虑车况、配置 / 等级差异或行驶里程（详见“已知限制”）。在依据这些数据做出任何买卖决定前，请务必先在 carsensor.net 上核实具体车辆的价格。

适用对象

• 需要让“这辆车实际值多少钱？”这一回答以真实市场数据为依据的 AI Agent 和聊天机器人，而不是依赖模型自身对二手车定价的认知（这些认知往往过时或存在幻觉）
• 开发汽车选购、估值或置换估价功能的应用 / 工具开发者，希望直接使用现成的价格区间查询工具，而不是自行抓取数据并维护 carsensor.net 集成
• 任何希望通过普通 MCP 工具调用来使用此服务，而非进行批量抓取的人——此 Actor 是面向单次调用、按需使用的工具，对应于我们的批量处理 Actor carsensor-resale-value-scout（它会根据相同的底层市场数据为整批车辆刊登信息评分）

它无法做到什么（集成前请阅读）

• **目前不支持将行驶里程作为输入。**仅使用车型和年份——价格区间反映的是 carsensor 自有的车型年份汇总数据，并非根据里程调整后的估算值。未来版本可能会添加此功能。
• 对于不熟悉的车型，首次使用时解析车型名称偶尔可能失败或耗时较长——原因以及缓存如何在首次调用后缓解这一问题，详见“已知限制”。
• **这是统计估算值，并非车辆鉴定估价。**请参阅上方的免责声明。

输入 / 输出

输入（MCP 工具调用参数）：

参数	类型	必填	描述
carModel	字符串	是	车型名称，格式与 carsensor 自身搜索使用的自由文本相同（例如 "プリウス"、"N-BOX"）
year	整数	是	车型年份，4 位数字（例如 2018）

输出（成功时）：

字段	类型	描述
priceRangeYen.min / .max / .median	整数（日元）	该车型 / 年份的估算市场价格区间
sampleSize	整数	用于汇总估算的 carsensor 车辆列表数量
confidence	"normal" | "low"	当年份仅匹配 carsensor 数据中的开放区间时为 "low"（参见“已知限制”）——发生这种情况时，会通过 note 字段说明原因
cacheStatus	对象	tier1 / tier2——此调用是否命中缓存数据，或向 carsensor.net 发起了新请求（仅供参考，不影响价格——参见“定价”）

输出（未找到车型 / 该年份无数据）：{ "ok": false, "reason": "no_code_resolved" | "no_matching_data", "message": "..." }——不收费（参见“定价”）。

使用示例

Claude Desktop / 任意 MCP 客户端配置：

{
  "mcpServers": {
    "carsensor-price-range": {
      "url": "https://woolen-snake--carsensor-price-range-mcp.apify.actor/mcp",
      "headers": { "Authorization": "Bearer YOUR_APIFY_TOKEN" }
    }
  }
}

在自己的应用中直接调用（Node.js、@modelcontextprotocol/sdk）：

import { Client } from '@modelcontextprotocol/sdk/client/index.js';
import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';

const transport = new StreamableHTTPClientTransport(
  new URL('https://woolen-snake--carsensor-price-range-mcp.apify.actor/mcp'),
  { requestInit: { headers: { Authorization: `Bearer ${process.env.APIFY_TOKEN}` } } },
);
const client = new Client({ name: 'my-app', version: '1.0.0' });
await client.connect(transport);

const result = await client.callTool({
  name: 'resolvePriceRange',
  arguments: { carModel: 'プリウス', year: 2018 },
});
console.log(JSON.parse(result.content[0].text));

定价

事件	价格	触发条件
成功解析价格区间（resolve-price-range-success）	$0.03	仅当 resolvePriceRange 成功返回价格区间时收费。无法解析车型或没有匹配的年份数据时不收费

无论调用是命中缓存数据还是触发了对 carsensor.net 的新请求，定价均为固定金额—— 有关完整理由（包括为何有意不采用按缓存层级定价），请参见下文“价格设定依据”。

价格设定依据

$0.03 介于此 Actor 系列的基础分类层级（$0.015，例如 carsensor-resale-value-scout Actor 上的 listing-extracted）和更复杂的派生信号层级（$0.045–$0.065，例如 value-score-computed）之间——这体现了价格区间是计算得出的市场信号，而非原始数据获取； 同时，此工具的底层基础设施成本（远低于 $0.001/次调用，大多数调用由缓存提供服务）无论如何都留有 很大的利润空间。

为何缓存命中和未命中的定价相同：无论哪种情况，交付的价值——priceRangeYen、sampleSize、 confidence——都相同；缓存只是内部的性能 / 成本优化，不会改变你获得的内容。差异化定价还会造成 反常激励，促使缩短缓存 TTL（未命中越多 = 收入越高），这会直接违背此工具尽量减少对 carsensor.net 负载的设计目标。

数据来源与计算

使用 carsensor.net 自行公开发布的已解析车型市场价格页面 （/usedcar/souba/{makerCode}_S{modelCode}/），具体使用其中的“价格 × 车型年份”交叉表 （价格区间、年份区间、每个单元格中的列表数量）——这是 carsensor 根据其自身实时库存计算的官方汇总数据， 并非第三方估算。

• median 是对每个匹配的年份区间的价格区间中点按数量加权后计算出的平均值
• min / max 取自匹配单元格中实际价格区间的边界（对于开放区间，例如“¥4,150,000 以上”， 使用 ±15% 的启发式方法进行近似——这是一种经验调整，并非统计推导结果）
• 这是按车型等级汇总的数据（例如所有 Toyota Prius 配置合并），并非单个车辆列表的定价—— 不考虑配置等级差异、设备或车况

缓存（两级）

层级	键	值	存储方式	过期时间
1	车型名称	{ makerCode, modelCode }	文件持久化	无限期（carsensor 的车型编码实际上是静态的）
2	{makerCode}_S{modelCode}	carsensor 的价格×车型年份单元格	文件持久化	12 小时

两级缓存均命中时，该次调用不会向 carsensor.net 发送任何 HTTP 请求。在托管于 Apify 的版本中，此缓存的范围仅限于单个 Standby 运行／容器实例——并发会话可能会分配到具有独立缓存的不同容器实例，因此托管版本在实际使用中的命中率可能低于单个长期运行的本地进程。未来版本可能会将缓存迁移至 Apify 的 Key-Value Store（在不同运行之间共享），前提是实际使用中确有此需求。

访问间隔与日志记录

向 carsensor.net 发送请求的间隔至少为 1000ms（默认 1500ms），以减少负载——与我们的 carsensor-resale-value-scout Actor 使用的最低间隔相同。每次调用都会记录日志（车型、年份、各级缓存的命中／未命中、实际发送的 HTTP 请求、响应时间、结果），以供日后监控——这些信息不会提供给调用方，仅用于负责任地运行此 Actor。

常见问题

为什么 confidence 有时是 "low"？ carsensor 自身的数据中，年份轴的底部有一个不设下限的区间（例如“2012 年或更早”）。任何不晚于该界限的年份都会与此区间匹配，无论该车型在那一年是否已实际存在——仅凭这些数据无法完全验证合理性，因此会如实降低 confidence，而不是将结果报告为确定值。具体原因请参见此类响应中的 note 字段。

为什么我首次查询某个车型要花几秒钟，而后续查询快得多？ 首次查询未识别的车型时，最多需要向 carsensor.net 发送 3 次实际请求（搜索 → 详情页 → 市场价格页），以确定车型。确定后，车型→代码的映射实际上会永久缓存，价格数据本身则缓存 12 小时，因此再次查询同一车型几乎会即时返回结果。

这会考虑行驶里程吗？ 暂不支持——请参见“它不能做什么”。

这与 carsensor-resale-value-scout 有什么区别？ 那个 Actor 是一个批量抓取工具：输入搜索词，获取一组实时在售列表，并依据同一市场数据为每条列表评分。这个 Actor 则是按需单次调用的对应工具，面向只需要获取某个车型／年份的一个数值、而非需要抓取并处理列表的 AI Agent 和应用。

已知限制

• 车型名称解析没有直接查询接口——它会通过 carsensor 自带的自由关键词搜索，并读取匹配列表的页面来识别车型。 对于确实无法识别的车型（拼写错误、不存在的车型），carsensor 的搜索结果页仍会包含一个“你可能也喜欢”组件，其中有无关车型；此 Actor 会明确检测并排除该组件，以免误将其识别为真实匹配——已通过实时测试确认。
• confidence 无法完全验证所查询年份对指定车型是否合理——请参见常见问题。
• 这是按等级汇总的价格，不是单条在售列表的价格——请参见“数据来源与计算”。
• 托管版本（Apify Standby）的文件缓存按容器隔离——请参见“缓存”。
• 此工具底层的抓取逻辑刻意从 carsensor-resale-value-scout 的代码库中复制，而非导入，以使这两个独立部署的 Actor 保持解耦。carsensor.net 的标记变更如果影响其中一个，可能也需要在另一个中进行相应修复。
• 未在 Smithery 上架：Apify Standby 的身份验证响应不符合 OAuth 发现规范，因此 Smithery 会在触及此服务自身基于配置的身份验证之前，自动连接扫描就已失败——目前暂无计划提供变通方案。

可能的后续扩展（此版本尚未实现）

• 将里程作为第三个输入，使用 carsensor 的价格×里程矩阵（已确认可以获取，但尚未接入）
• 将缓存迁移到 Apify 的键值存储，以便在 Standby 容器实例之间共享
• 除 Apify Store 外，在其他 MCP 目录中上架