Vin Recall MCP README
The full upstream README, mirrored here for reference. Install config, tool schemas, adoption signals, and an original overview live on the Vin Recall MCP listing page.
vin-recall-mcp
A remote MCP server that gives any MCP client (Claude, or any other MCP-compatible agent) two tools for free U.S. government vehicle data: decode a VIN and check open safety recalls, both backed by NHTSA's public APIs.
What it does
vin-recall-mcp exposes two tools over a single Streamable HTTP endpoint: decode_vin, which turns a 17-character VIN into make, model, year, body class, engine, fuel type, and assembly plant using NHTSA's vPIC database; and check_recalls, which decodes that same VIN internally and returns every open safety recall campaign NHTSA has on file for that vehicle configuration. Point an MCP client at the URL below and ask it a plain-English question — no API key, no signup, no auth.
Why it exists
NHTSA's vPIC and Recalls APIs are free and genuinely useful, but they're not built for a conversation. decodevin alone returns 100+ key/value pairs per VIN, most of them empty or the literal string "Not Applicable". The recalls endpoint returns HTTP 400 for a legitimate zero-results case, the exact same status it uses for a bad request. Response times swing from a quarter-second to several seconds on the same VIN. None of that is something you want an agent — or a human — parsing raw. This server does the flattening, validation, timeout handling, and error translation once, so an MCP client can just ask "what's this VIN, and does it have any open recalls?" and get a clean answer back.
Architecture
The server is a stateless Node/Express process using @modelcontextprotocol/sdk's StreamableHTTPServerTransport — a fresh McpServer per request, no sessions, no database, no auth layer. It's self-hosted on-prem (Ubuntu Server, "Zenith") behind a Caddy reverse proxy for HTTPS termination, rather than a serverless platform, so the tools run under a real long-lived process with straightforward logs and no cold starts. Tool logic (src/tools.ts) is fully decoupled from the transport (src/server.ts), so it can be — and is — imported and tested directly by the eval suite without a running server.
Tools
decode_vin
Decode a 17-character US VIN into vehicle attributes.
| Input | vin (string, required) — 17 characters, letters and digits, excluding I, O, Q |
| Output | make, model, year, bodyClass, engineCylinders, fuelType, driveType, plantCountry (each omitted if NHTSA has no meaningful value), a one-line summary, and a found flag |
| Coverage | US-market vehicles from the 1981 17-character VIN standard onward |
check_recalls
List open NHTSA safety recall campaigns for a vehicle, by VIN.
| Input | vin (string, required) — same 17-character format; decoded internally to get make/model/year, so there's no separate make/model/year input path |
| Output | checked flag, make/model/year, recallCount, and a recalls array — each with campaignNumber, summary, consequence, remedy, reportDate, and the parkIt/parkOutside safety flags where NHTSA provides them |
| Zero recalls | Returns an explicit "No open recall campaigns found for this vehicle," never a silent empty array |
Install
Live endpoint: https://vin-recall-mcp.zenithserver.duckdns.org/mcp
Claude.ai / Claude web: Settings → Connectors → Add custom connector → paste the URL above.
Claude Desktop (or any client that needs a local proxy) — add to your MCP config, using mcp-remote:
Once connected, just ask naturally: "Can you decode VIN JM3KFBCM1R0123456 and tell me if it has any open recalls?"
Caveats
These aren't polish — they're correctness constraints this server is built around:
- A recall campaign is not proof of a repair.
check_recallsreturns campaigns issued for a make/model/year configuration. It never confirms whether the specific VIN's vehicle was actually fixed at a dealer — that record isn't public. Every non-empty result carries this disclaimer. - Coverage gap by design, not by bug. vPIC reliably decodes US-market vehicles from the 1981 17-character VIN standard onward. Pre-1981 VINs are shorter by definition and are rejected by input validation before any network call; some foreign-market vehicles may also return partial or no data. Either way you get a clean "not found" message, never a crash.
- NHTSA is slow, and inconsistently so. Real-world response times for the same VIN have ranged from ~0.3s to 3s+ in testing. Every outbound request carries a 9-second timeout; a timeout returns a plain "NHTSA is slow or unavailable, try again," never a hang or a stack trace.
- Decoded fields are manufacturer-submitted. NHTSA doesn't guarantee every field is populated even for a VIN that decodes successfully. Missing fields are silently dropped rather than shown as empty, and a note is attached whenever NHTSA's own error code flags the decode as non-clean.
Evals
evals/ contains 9 cases exercising both tools against the real NHTSA APIs (deliberately not mocked — the point is proving the tool logic survives NHTSA's actual response shapes, not a fake of them): a known-good modern VIN, a Tesla, a truck, a motorcycle, a malformed VIN, a pre-1981-length VIN, a well-formed-but-undecodable VIN, a VIN with known open recalls, and a VIN with none. Each case asserts on error/success state, required substrings, structured-content fields, and — for successful results — that the output actually satisfies the tool's declared Zod outputSchema.
This also runs automatically on every pull request against main (see .github/workflows/pr-checks.yml), alongside a type-check.