io.github.carvectorio/carvector-mcp

carvector-mcp

Give your AI agent real vehicle data. An MCP server that lets Claude, Cursor, ChatGPT, or any MCP-capable client query the CarVector API natively — vehicle specs, representative images, federal recalls, owner complaints, service bulletins, defect investigations, and OBD-II diagnostic trouble codes.

Models hallucinate car data. They invent horsepower numbers, miss recalls filed last week, and guess at what a trouble code means. carvector-mcp gives your agent structured, sourced answers it can cite instead of a confident guess.

npx -y carvector-mcp --key cv_your_key

· MIT · Free tier, no card → carvector.io

Quickstart

1. Get a free API key at carvector.io — 500 requests a month, no credit card.

2. Add it to your MCP client. Most clients use an mcpServers block:

{
  "mcpServers": {
    "carvector": {
      "command": "npx",
      "args": ["-y", "carvector-mcp"],
      "env": { "CARVECTOR_API_KEY": "cv_your_key" }
    }
  }
}

That's it. Restart your client and ask it about a vehicle.

Prefer a remote server? If your client supports HTTP MCP, skip the install and point it straight at the hosted endpoint:

{ "mcpServers": { "carvector": {
    "url": "https://api.carvector.io/v1/mcp",
    "headers": { "Authorization": "Bearer cv_your_key" } } } }

Tools

The agent chains them naturally: search_vehicles to resolve an id, then get_vehicle, get_recalls, get_complaints, get_tsbs, or get_investigations.

Example

You: "Is a P0300 code serious?"

→ carvector.lookup_dtc({ code: "P0300" })
{
  "code": "P0300",
  "title": "Random/Multiple Cylinder Misfire Detected",
  "category": "Powertrain",
  "severity": "High",
  "safety_risk": true,
  "emissions_related": true
}

Your agent answers: "Yes — P0300 is a high-severity, safety-related misfire code. Don't keep driving on it." Sourced, not guessed.

Three things to build with it

• A service-advisor copilot that pulls a customer's exact trim, open recalls, the manufacturer's documented fix (TSBs), the complaint pattern behind a symptom, and a decoded check-engine code — in one turn, no tab-switching.
• A consumer car chatbot that answers "what engine does my truck have" and "is it under recall" with real data instead of a hallucination.
• A coding/automotive agent that needs structured vehicle knowledge as a tool, not a wall of scraped text to parse.

Paying per call instead of using a key (x402)

The CarVector HTTP API also accepts x402 payments, so an agent with a wallet can call it with no account, no signup and no API key — it pays per request and gets the data back.

• $0.01 USDC per call, on Base mainnet (USDC 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913)
• Request a paid endpoint without payment and you get an HTTP 402 with everything needed to pay and retry:

curl -i "https://carvector.io/v1/vehicles?year=2020&make=Ford&model=F-150"
# HTTP/1.1 402 Payment Required
# { "x402Version": 1, "accepts": [ { "scheme": "exact", "network": "base", ... } ] }

Payable endpoints: /v1/vehicles, /v1/vehicles/:id, /v1/vehicles/:id/recalls, /v1/vehicles/:id/complaints, /v1/vehicles/:id/tsbs, /v1/vehicles/:id/investigations, /v1/dtc/:code.

This MCP client does not pay — it uses an API key. carvector-mcp requires CARVECTOR_API_KEY and exits without one. x402 is for calling the HTTP API directly. If you want keyless access from an agent, call the endpoints above rather than going through this package.

About the data

carvector-mcp is an open-source, thin client. It bundles no data — every call forwards to the CarVector API, authenticated with your key. What you get back:

• Vehicles — a broad catalog (1925–2029), broken out by trim and engine variant, with representative illustrations (not photos).
• Recalls — federal recall campaigns mapped to year / make / model.
• Complaints — owner-filed complaints aggregated by component (with crash / fire / injury counts) plus the most recent filings, mapped to a vehicle. (Pro plan.)
• Service bulletins (TSBs) — the manufacturer's technical service-bulletin index — metadata, not the documents. (Business plan.)
• Investigations — federal defect investigations, a leading indicator that often precedes a recall. (Business plan.)
• DTC reference — OBD-II codes classified by category, severity, and safety/emissions flags. Reference only — repair-cost economics is on the roadmap, not in responses today.

Calls count against your plan's rate limit and show up in your dashboard, exactly like a REST request.

Open source & your key

This client is ~150 lines of readable JavaScript — please read them. It:

• talks to one host only — api.carvector.io (grep index.js, it's the only URL),
• sends your key only as a Bearer header to that host, nowhere else,
• has zero telemetry, analytics, or phone-home, and writes nothing to disk,
• depends on exactly one package: the official @modelcontextprotocol/sdk.

Your key stays on your machine. Set it via the CARVECTOR_API_KEY env var (preferred); --key works too but, like any CLI argument, is visible in process listings.

License

MIT. The client is open source; the data is served by CarVector.