car-falcon-mcp

[](LICENSE) [](https://www.python.org/downloads/) [](https://modelcontextprotocol.io)

An MCP (Model Context Protocol) server that searches, tracks, and analyzes used car listings across multiple sites. Designed to work with Claude Code or any MCP-compatible AI agent.

Car Falcon runs a 4-phase pipeline on each search:

1. Fetch — Searches listing sites in parallel using pluggable site modules
2. Validate — Filters results by price, year, mileage, condition, and damage patterns
3. Enrich — Checks VINs against NHTSA (recalls/complaints) and estimates fair market value via KBB
4. Report — Generates a styled HTML report with deal ratings, price history, and photos — optionally emailed via Gmail SMTP

<details> <summary>Interactive version</summary>

Open architecture.html locally in a browser for the full interactive diagram. </details>

• Multi-site search — Searches multiple car sources in parallel (pluggable site architecture)
• VIN checking — Queries NHTSA for recalls and complaints
• Market valuation — Estimates fair value via KBB or heuristic fallback
• Deal rating — Rates listings from "Great Deal" to "Overpriced"
• Price tracking — Detects price drops across runs
• HTML reports — Generates styled email-ready reports with photos and deal badges
• Email delivery — Sends reports via Gmail SMTP

pip install -e .
playwright install chromium firefox

Copy config.example.yaml to config.yaml and fill in your values:

cp config.example.yaml config.yaml

Key settings:

• searches — Define make, model, year range, price c