carsearch-mcp
carsearch — 加拿大二手车搜索、监控与市场分析平台
carsearch 将加拿大市场列表转化为持久化、可搜索的历史数据库，并通过 MCP 将其暴露给 Claude Code（或任何智能体），同时提供完整的 CLI。它从 AutoTrader.ca 收集真实列表（更多数据源可插拔），将每次价格/状态变化作为历史记录，跨列表对实际车辆去重，正确进行地理编码（真实距离），从描述中提取风险信号，计算可比价格统计，根据可配置配置文件对项目车评分，检测交易，按计划重新运行已保存搜索并发出警报。
你可以这样问 Claude：
找一下多伦多 800 公里内、$8,000 以下的所有手动挡 BMW E90 328i，优先个人卖家，排除锈蚀严重车辆，按项目车价值排序。
过去 48 小时内安大略省出现了哪些 $7k 以下的有趣项目车？
这辆 $6,200 的 Audi TT 相对于我们观察到的类似列表是否真的便宜？
显示本周所有降幅 > 10% 的价格。 / 已上架 30 天以上且卖家已降价两次的车。
各阶段状态、测试命令和已知问题：PROJECT_STATUS.md。
架构（简要）
providers/ (autotrader ✓, cargurus/kijiji/facebook interface+probe) → VehicleListing (canonical)
→ collectors/ (checkpointed ProviderRun, ingest w/ snapshots+events, raw payloads)
→ dedupe/ (VIN → weighted soft signals → vehicles + candidates) → geo/ (geocode, haversine)
→ SQLite/PostgreSQL (SQLAlchemy) → search/ analysis/ (description, comps, deals, market)
→ scoring/ (profiles + model knowledge JSON) → monitoring/ (saved searches, scheduler) → notifications/
→ cli/ (carsearch …) and mcp/ (23 tools)详细信息：docs/architecture.md、docs/providers.md、docs/schema.md。
安装
python3 -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]" # add ".[postgres]" for PostgreSQL
cp .env.example .env # optional; SQLite in ./data works out of the box
carsearch db-init # creates/upgrades data/carsearch.dbPython ≥ 3.11（在 3.14 上开发）。无需浏览器，AutoTrader 不需要 API 密钥。
数据库设置
默认：
sqlite:///./data/carsearch.db（WAL）。无需任何操作。PostgreSQL：在
.env中设置CARSEARCH_DATABASE_URL=postgresql+psycopg://user:pass@host/carsearch，运行pip install -e ".[postgres]"，然后执行carsearch db-init。Schema/迁移文件位于src/carsearch/database/（带版本号，记录在schema_migrations中）。
爬取（收集真实数据）
# targeted, with detail pages for new listings (VIN, exact coordinates, drivetrain, created date)
carsearch crawl autotrader --make BMW --model "3 Series" --transmission manual --max-price 8000 --min-year 2006 --max-year 2013 --details new
# regional bulk (20 listings/page, ~1.5 s/page, no detail pages)
carsearch crawl autotrader --max-price 7000 --location Toronto --radius-km 500 --max-pages 200 --details none
# province scope (centroid + covering radius server-side, exact province locally)
carsearch crawl autotrader --province ON --transmission manual --max-price 6000 --seller-type private
# incremental refresh: stop after 3 consecutive pages with nothing new/changed
carsearch crawl autotrader --transmission manual --max-price 8000 --stop-when-seen 3
# resume an interrupted run
carsearch crawl autotrader --resume 12
# re-check listings not seen for 3 days (marks removed on 404); fetch missing detail pages; geocode backfill
carsearch refresh autotrader --older-than-days 3 --limit 200
carsearch details autotrader --limit 200
carsearch geocode --limit 60
scripts/bootstrap_crawl.sh # example multi-band bootstrap used to seed the DBAutoTrader 将单个查询限制为 200 页（4000 条列表）→ 按价格区间/地区拆分以覆盖全部（运行摘要中的 truncated=True 会提示你）。
搜索
carsearch search --make BMW --model 328i --max-price 7000 --transmission manual --location Toronto --radius-km 800 --seller-type private
carsearch search --generation E90 --keywords '"one owner" -salvage' --province ON,QC --sort price_asc
carsearch new --since 48h --province ON --max-price 7000
carsearch price-drops --min 10 --since 7d
carsearch deals --province ON --max-price 7000 --profile project_car_enthusiast
carsearch deals --location Toronto --radius-km 500 --transmission manual --max-price 7000 --since 7d \
--profile project_car_enthusiast --sort-by project --exclude-flags salvage_title,frame_rust,doesnt_run # "best project cars" ranking
carsearch listing 42 # full record + price history + description flags
carsearch history 42 # snapshots + change events
carsearch comps 42 # comparable-price analysis with methodology
carsearch score 42 --profile project_car_enthusiast
carsearch analyze 42 # everything above + deal signals in one JSON
carsearch market --metric manual_premium --make Subaru --model WRX
carsearch market --metric price_by_mileage --generation E90 --province ON
carsearch market --metric cheapening --days 90
carsearch status [--check-providers] · carsearch runs · carsearch alerts每个命令都接受 --json 以输出机器可读的结果。
监控 / 已保存搜索 / 警报
carsearch saved seed # the four example searches from the brief
carsearch saved create "manual E90 328i under $8k" '{"make":"BMW","model":"3 Series","min_year":2006,"max_year":2011,"max_price":8000,"transmission":"manual"}' \
--interval-minutes 240 --alert-rules '{"price_drop_pct":10,"target_price":6500,"min_deal_score":65}' --profile project_car_enthusiast
carsearch saved run "manual E90 328i under $8k" # incremental crawl → new listings + alerts
carsearch schedule # long-running loop: runs due searches, maintenance
carsearch schedule --once # one pass (cron-friendly)警报发送到控制台、data/alerts.jsonl 和可选 webhook（CARSEARCH_WEBHOOK_URL）；新增接收端 = 继承 notifications.alerts.AlertSink。每条警报都带有 reasons[]（以及风险）。
MCP 服务器
carsearch serve-mcp # stdio (default) | --transport streamable-http --port 8765工具：search_cars、search_live_marketplace、get_listing、get_vehicle、get_new_listings、get_price_history、get_listing_changes、get_comparables、compare_cars、find_deals、find_price_drops、find_long_sitting_listings、analyze_listing、score_listing、analyze_market、list_saved_searches、create_saved_search、run_saved_search、delete_saved_search、get_alerts、get_status、get_generation_codes、analyze_listing_images。所有这些工具都返回带分页的结构化 JSON（limit/offset/next_offset）；重量级字段（description、photos、raw）为可选。
连接 Claude Code
claude mcp add carsearch -- /ABSOLUTE/PATH/autotrader/.venv/bin/carsearch serve-mcp
# or in .mcp.json:
{ "mcpServers": { "carsearch": { "command": "/ABSOLUTE/PATH/autotrader/.venv/bin/carsearch", "args": ["serve-mcp"] } } }然后：“查找过去一周内出现在多伦多 500 公里内、$7,000 CAD 以下的最佳手动挡项目车。将它们与历史价格进行比较，标记列表中的重要机械/锈蚀风险，并排出前 10 名。” — Claude 通常会调用 search_cars/get_new_listings（或 search_live_marketplace 获取新数据），然后调用 analyze_listing/compare_cars。
检查点如何工作
每次爬取对应一行 provider_runs。在每一页之后，列表被提交，last_checkpoint.next_page 被推进；单个列表的失败记录在 errors 中并跳过。详情丰富按列表提交（detail_fetched_at）。运行中断时标记为 failed/interrupted，carsearch crawl --resume <id> 会从 next_page 继续（已抓取的页面来自本地 http_cache）。已保存搜索的状态保存在数据库中。参见 docs/architecture.md。
如何添加数据源
在 src/carsearch/providers/<name>/ 中实现 BaseProvider，在 parser.py 中映射到 VehicleListing（保留 raw），注册它，添加 fixtures 和测试，并在 docs/providers.md 中记录。其他无需更改。
测试
pytest -q # 42 tests: normalization, parser fixtures, ingest/price history, dedupe,
# geo/search, analysis (flags/comps/scoring/deals/market), crawler checkpoints, MCP tools没有任何测试会接触网络（使用真实负载 fixtures 和一个假数据源）。
已知限制
数据源：目前只有 AutoTrader.ca 在采集。CarGurus（DataDome）、Kijiji（edge 403 / kijijiautos.ca 已不可用）和 Facebook（需登录）都是带有实时健康探测的接口；不会尝试绕过反机器人或登录（参见
docs/providers.md）。标价，而非成交价。 列表消失 ≠ 已售出；我们会记录
not_observed/removed。覆盖范围 取决于你爬取的内容（每个查询 200 页上限；按区间拆分）。“过去 N 天出现”在已知时使用市场上的创建日期（详情页），否则使用我们的首次观察时间。
坐标：对于有详情页的列表是精确的；否则为城市级别（种子表 / 学习的质心 / 市场解析器）。距离过滤器会跳过没有坐标的列表。
评分、标记和优惠分数是启发式的，带有明确的证据和可配置规则（
src/carsearch/config/*.json）；它们是推理的输入，而非结论。正则表达式标记可能会在异常措辞上误报（始终会返回证据）。可比列表使用渐进放宽；小样本会被标记（
warnings、confidence）。图像分析附带哈希/缓存和一个可插拔的视觉钩子（包含 Anthropic 后端，默认关闭）；除非配置，否则不会运行任何视觉模型。
SQLite 可以处理数十万条列表；对于并发写入，请切换到 PostgreSQL。
This server cannot be installed
Maintenance
Resources
Unclaimed servers have limited discoverability.
Looking for Admin?
If you are the server author, to access and configure the admin panel.
Related MCP Connectors
MCP server for CarsXE vehicle data: VIN, specs, history, images, recalls, and OBD codes.
MCP server for AI job search — find jobs, track applications, get alerts. Claude, ChatGPT, Cursor.
An MCP server for deep research or task groups
Latest Blog Posts
- Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)By Om-Shree-0709 on .mcpAgent IdentityOAuth 2.1
- Your AI Chatbot Just Exposed Your CEO's Salary to an InternBy Om-Shree-0709 on .Agent IdentityMCP SecurityOAuth Delegation
- Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)By Om-Shree-0709 on .Agentic AiPrompt InjectionWebAssembly
MCP directory API
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/Lironktf/carsearch'
If you have feedback or need assistance with the MCP directory API, please join our Discord server