Tools

Seven tools for querying NHTSA vehicle safety data:

nhtsa_get_vehicle_safety

Composite safety profile — the default tool when asked about vehicle safety, reliability, or purchase decisions.

• Combines NCAP crash test ratings, recall history, and complaint summary in a single response
• Frontal crash, side crash, and rollover ratings per vehicle variant
• Complaint breakdown by component with crash, fire, injury, and death counts

nhtsa_search_recalls

Search recall campaigns by vehicle or campaign number.

• Look up by make/model/year or by specific NHTSA campaign number
• Optional date range filtering (ISO 8601)
• Includes do-not-drive advisories, park-outside warnings, and OTA update availability

nhtsa_decode_vin

Decode Vehicle Identification Numbers for manufacturing and safety details.

• Single VIN or batch decode up to 50 VINs
• Partial VINs accepted — use * for unknown positions
• Returns make, model, year, body type, engine specs, airbag locations, ESC, ABS, and traction control

nhtsa_search_investigations

Search NHTSA defect investigations.

• Investigation types: Preliminary Evaluations, Engineering Analyses, Defect Petitions, Recall Queries
• Free-text search across subjects and descriptions
• First query loads the full investigation index (~10s); subsequent queries use a cached index (1h TTL)

nhtsa_search_complaints

Search consumer safety complaints filed with NHTSA.

• Component breakdown with crash, fire, injury, and death counts
• Optional component filter (e.g., "ENGINE", "AIR BAGS")
• Returns up to 50 most recent complaints sorted by filing date

nhtsa_get_safety_ratings

NCAP crash test ratings and ADAS feature data.

• Frontal crash, side crash (barrier + pole), and rollover ratings
• ADAS features: ESC, forward collision warning, lane departure warning
• Counts of complaints, recalls, and investigations on file

nhtsa_lookup_vehicles

Reference lookups against NHTSA's VPIC database.

• Four operations: makes, models, vehicle_types, manufacturer
• Use to resolve ambiguous vehicle names or verify correct spelling
• Models can be filtered by year; manufacturers support partial match

Features

Built on @cyanheads/mcp-ts-core:

• Declarative tool definitions — single file per tool, framework handles registration and validation
• Unified error handling across all tools
• Pluggable auth (none, jwt, oauth)
• Swappable storage backends: in-memory, filesystem, Supabase, Cloudflare KV/R2/D1
• Structured logging with optional OpenTelemetry tracing
• Runs locally (stdio/HTTP) from the same codebase

NHTSA-specific:

• Type-safe client wrapping five NHTSA public APIs with retry logic and field normalization
• Investigation index caching (1h TTL) for fast repeated queries
• No API key required — all NHTSA APIs are public

Getting started

Add to your MCP client config (e.g., claude_desktop_config.json):

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

Or with npx (no Bun required):

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

Or with Docker:

{
  "mcpServers": {
    "nhtsa-vehicle-safety": {
      "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.3.2 or higher (or Node.js >= 22.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

Configuration

No API keys required — all NHTSA APIs are public.

Data sources

All data comes from NHTSA's public APIs:

• Recalls API — api.nhtsa.gov/recalls
• Complaints API — api.nhtsa.gov/complaints
• Safety Ratings API — api.nhtsa.gov/SafetyRatings
• Investigations API — api.nhtsa.gov/investigations
• VPIC API — vpic.nhtsa.dot.gov/api/vehicles

Running the server

Local development

bun run dev:stdio     # Dev mode with hot reload (stdio)
bun run dev:http      # Dev mode with hot reload (HTTP)

• Run checks and tests:

  bun run devcheck  # Lints, formats, type-checks, and more
  bun run test      # Runs the test suite
  

Production

bun run build
bun run start:stdio   # Production stdio
bun run start:http    # Production HTTP

Docker

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

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 logging
• One tool per file, nhtsa_ prefix for all tool names

Contributing

Issues and pull requests are welcome. Run checks before submitting:

bun run devcheck
bun run test

License

Apache-2.0 — see LICENSE for details.