Nhtsa Vehicle Safety Mcp Server

Overview

Vehicle safety data from NHTSA: recalls, consumer complaints, NCAP crash ratings, defect investigations, and VIN decoding. Get a full safety picture for any make, model, and year in one call, or decode a VIN.

Tools

Capability reference

nhtsa_get_vehicle_safety _tool

• Combines NCAP crash test ratings, recall history, and complaint summary in a single response
• Frontal crash, side crash, and rollover ratings per vehicle variant
• Recall consequence text plus the do-not-drive, park-outside, and over-the-air-update advisories; summary, consequence, and remedy are omitted for older campaigns whose record leaves them blank
• Complaint breakdown by component with crash, fire, injury, and death counts
• Returns sectionStatus (available/partial/unavailable per section) plus warnings so a partial NHTSA outage is not mistaken for a clean record
• When recalls or complaints come back empty, a notice points at nhtsa_lookup_vehicles with operation="dataset_models", because NHTSA can file one vehicle under different model names in each dataset

nhtsa_search_recalls _tool

• Three modes: campaignNumber; make + model + modelYear together; or a broad search with any other combination of make, model, modelYear, and dateRange. campaignNumber is mutually exclusive with the vehicle fields
• Campaign lookups return every make/model the campaign covers, plus the ODI investigation that preceded it; a 6-character number (e.g., 00V419) returns every campaign it covers
• Broad search returns campaigns newest received date first with an exact totalCount, up to 50 per page (default 20) with limit and offset, and a larger limit is lowered to 50 with a notice; both are rejected with the other two modes. A campaign matches when one of its vehicle records carries every vehicle filter, compared against whole make and model names, ignoring case
• NHTSA may file a vehicle's recalls under a series name or a base name; search both. A broad search's received date can fall one day before the date the other modes report for the same campaign
• Optional inclusive dateRange bounds (after/before, calendar-valid YYYY-MM-DD) apply in every mode; blank bounds are unset
• Includes do-not-drive advisories, park-outside warnings, and OTA update availability (never set by a broad search)

nhtsa_search_complaints _tool

• Component breakdown covers every matching complaint regardless of pagination; up to 50 complaint narratives per page (default 20), offset pagination, sorted by filing date descending. A larger limit is lowered to 50 with a notice naming the next offset (see NHTSA_CLAMP_LIMITS)
• Optional component filter matches case-insensitively within each component name a complaint lists (e.g., "ENGINE", "AIR BAGS"); component names can themselves contain ", " (e.g., "SERVICE BRAKES, HYDRAULIC")
• Every component line includes crash, fire, injury, and death totals, including zeros; individual complaints preserve fields NHTSA actually reported
• An incident date NHTSA reported that the complaint's own filing date or model year rules out is disclosed as unreliableIncidentDate rather than served as the incident date

nhtsa_get_safety_ratings _tool

• Accepts either make + model + modelYear, or a follow-up vehicleId from an earlier result; combining the modes is rejected
• Frontal crash, side crash (barrier + pole), and rollover ratings, plus ESC/forward-collision/lane-departure ADAS availability
• Per-record complaint, recall, and investigation counts are variant-scoped — not vehicle-level totals
• NCAP coverage starts at 1990, most complete for 2011+ model years

nhtsa_decode_vin _tool

• One VIN, or several in an array or in one string separated by spaces, semicolons, or commas; partial VINs accepted using * for unknown positions, each as its own entry
• A call decodes up to 50 VINs and accepts up to 500; the rest come back in deferredVins to pass back as vin. VIN,YYYY gives one VIN its own model year; optional modelYear covers the others
• A blank entry, a character other than a letter, digit, or *, or a VIN over 17 characters is rejected before decoding (empty_vin_list, invalid_vin)
• Safety equipment includes VPIC's driver-assistance features (automatic emergency braking, lane keeping, blind spot warning, backup camera, adaptive cruise control, and others); Optional means the configuration offers the feature, not that this vehicle has it
• Preserves sparse VPIC fields instead of filling missing data with placeholders; every result carries VPIC's own errorCode/errorText decode-quality signal, including the clean "0" case

nhtsa_search_investigations _tool

• Investigation types: Preliminary Evaluations (PE), Engineering Analyses (EA), Defect Petitions (DP), Recall Queries (RQ), Audit Queries (AQ), and additional ODI codes (SQ, EQ, RP, and others)
• Free-text search across investigation IDs, subjects, and summaries, plus structured make, model, modelYear, and component filters — all ANDed. make, model, and modelYear must all match the same vehicle association; an investigation with no model year never matches a modelYear
• Results are ordered newest-opened first. Rows list every linked manufacturers and recallCampaigns entry
• Search rows omit summary; set includeSummary: true to include it, or fetch one record with nhtsaId, which always returns it
• Inclusive openDateRange and closeDateRange bounds (after/before, calendar-valid YYYY-MM-DD) filter before counting and pagination; active bounds exclude records without the corresponding usable date
• nhtsaId fetches one investigation by its exact ID, mutually exclusive with the other filters — the reverse of the recall link, closing the campaign-to-investigation round trip
• Sourced from NHTSA's ODI bulk file (FLAT_INV.zip), loaded on first use and cached for 24 hours
• Up to 50 investigations per page (default 20), offset pagination; a larger limit is lowered to 50 with a notice

nhtsa_lookup_vehicles _tool

• Five operations: makes, models, vehicle_types, manufacturer, dataset_models — models, vehicle_types, and manufacturer match partial names
• dataset_models (requires make and modelYear) lists the model names NHTSA's complaint, NCAP, and VPIC lists carry, each tagged listedBy products, ncap, or vpic. It takes the full make name (e.g., "Chevrolet"). Use it when a recall, complaint, or rating search comes back empty, then search under each name
• models can be filtered by year; models and vehicle_types both require make
• Each operation rejects inactive filters: makes accepts none, models and dataset_models accept make/modelYear, vehicle_types accepts make, and manufacturer accepts manufacturer. Optional blank strings are unset; operation-required make/manufacturer names must be nonblank
• Up to 200 results per page (default 100), offset pagination; a larger limit is lowered to 200 with a notice
• manufacturer lookups stop at a 500-record ceiling and disclose truncated when more may exist — VPIC publishes no match total

Features

Built on @cyanheads/mcp-ts-core: stdio and Streamable HTTP transports, pluggable auth (none / jwt / oauth), swappable storage (in-memory, filesystem, Supabase, Cloudflare KV/R2/D1), structured logging with optional OpenTelemetry tracing.

NHTSA-specific:

• Type-safe client wrapping four NHTSA JSON APIs with retry logic and sparse-field normalization, plus a streaming parser for NHTSA's investigation and recall bulk files
• Investigation and recall indexes cached for 24 hours; the bulk files load one at a time, and each load (waiting its turn, downloading, and parsing; both recall files count as one load) must finish within 120 s
• Published nhtsa-vehicle-safety-guide skill (skill://nhtsa-vehicle-safety-guide/SKILL.md) with the identifier chains and gates for merging results across model names, make versus manufacturer, model year versus received date, and what an empty or Not Rated result proves
• No API key required — all NHTSA APIs are public

Agent-friendly output:

• Provenance: every tool echoes effectiveQuery in its enrichment block, so callers can verify exactly what was searched
• Graceful partial failure: nhtsa_get_vehicle_safety returns sectionStatus per section plus warnings, so a partial NHTSA outage isn't mistaken for a clean safety record
• Discriminated outputs: unreliableIncidentDate (complaints), VIN decode errorCode/errorText, and manufacturer-lookup truncated disclose data-quality limits rather than silently omitting or fabricating values

Getting started

Public Hosted Instance

A public instance is available at https://nhtsa.caseyjhand.com/mcp — no installation required. Point any MCP client at it via Streamable HTTP:

{  "mcpServers": {    "nhtsa-vehicle-safety-mcp-server": {      "type": "streamable-http",      "url": "https://nhtsa.caseyjhand.com/mcp"    }  }}

Self-Hosted / Local

Add the following to your MCP client configuration file:

{  "mcpServers": {    "nhtsa-vehicle-safety-mcp-server": {      "type": "stdio",      "command": "bunx",      "args": ["@cyanheads/nhtsa-vehicle-safety-mcp-server@latest"],      "env": {        "MCP_TRANSPORT_TYPE": "stdio",        "MCP_LOG_LEVEL": "info"      }    }  }}

Or with npx (no Bun required):

{  "mcpServers": {    "nhtsa-vehicle-safety-mcp-server": {      "type": "stdio",      "command": "npx",      "args": ["-y", "@cyanheads/nhtsa-vehicle-safety-mcp-server@latest"],      "env": {        "MCP_TRANSPORT_TYPE": "stdio",        "MCP_LOG_LEVEL": "info"      }    }  }}

Or with Docker:

{  "mcpServers": {    "nhtsa-vehicle-safety-mcp-server": {      "type": "stdio",      "command": "docker",      "args": ["run", "-i", "--rm", "-e", "MCP_TRANSPORT_TYPE=stdio", "ghcr.io/cyanheads/nhtsa-vehicle-safety-mcp-server:latest"]    }  }}

For Streamable HTTP, set the transport and start the server:

MCP_TRANSPORT_TYPE=http MCP_HTTP_PORT=3010 bun run start:http# Server listens at http://localhost:3010/mcp

Prerequisites

• Bun v1.4.0 or higher (or Node.js >= 24.0.0)

Installation

1. Clone the repository:

git clone https://github.com/cyanheads/nhtsa-vehicle-safety-mcp-server.git

2. Navigate into the directory:

cd nhtsa-vehicle-safety-mcp-server

3. Install dependencies:

bun install

4. Configure environment (optional):

cp .env.example .env# edit .env to override transport, auth, or storage defaults — no API key required

Configuration

No API keys required — all NHTSA APIs are public.

See .env.example for the full list of optional overrides.

Running the server

Local development

• Build and run:

  sh

  # One-time buildbun run rebuild
  # Run the built serverbun run start:stdio# orbun run start:http

• Run checks and tests:

  sh

  bun run devcheck   # Lint, format, typecheck, securitybun run test       # Vitest test suitebun run lint:mcp   # Validate MCP definitions against spec

Docker

docker build -t nhtsa-vehicle-safety-mcp-server .docker run --rm -p 3010:3010 nhtsa-vehicle-safety-mcp-server

The Dockerfile defaults to HTTP transport and logs to /var/log/nhtsa-vehicle-safety-mcp-server; it restates the stateless session mode the server already declares. OpenTelemetry peer dependencies are installed by default — build with --build-arg OTEL_ENABLED=false to omit them.

Project structure

Development guide

See CLAUDE.md for development guidelines and architectural rules. The short version:

• Handlers throw, framework catches — no try/catch in tool logic
• Use ctx.log for request-scoped logging
• One tool per file, nhtsa_ prefix for every tool name, registered in createApp()
• Validate raw NHTSA responses → normalize to domain types → return the output schema; never fabricate a field NHTSA didn't provide

Data sources

All data comes from NHTSA's public APIs and bulk files:

• Recalls API — api.nhtsa.gov/recalls
• Complaints API — api.nhtsa.gov/complaints; dataset_models also reads its model-name list at api.nhtsa.gov/products/vehicle/models
• Safety Ratings API — api.nhtsa.gov/SafetyRatings
• Investigations bulk file — static.nhtsa.gov/odi/ffdd/inv/FLAT_INV.zip
• Recall bulk files — static.nhtsa.gov/odi/ffdd/rcl/FLAT_RCL_POST_2010.zip and FLAT_RCL_PRE_2010.zip, used by broad nhtsa_search_recalls searches
• VPIC API — vpic.nhtsa.dot.gov/api/vehicles

Contributing

Issues are welcome. Run checks and tests before submitting:

bun run devcheckbun run test

License

Apache-2.0 — see LICENSE for details.