.codex-plugin— mcp server

<div align="center"> <h1>@cyanheads/nhtsa-vehicle-safety-mcp-server</h1> <p><b>Decode VINs, search recalls, complaints, crash ratings, and investigations via MCP. STDIO or Streamable HTTP.</b> <div>7 Tools</div> </p> </div>

<div align="center">

</div>

<div align="center">

</div>

<div align="center">

Public Hosted Server: https://nhtsa.caseyjhand.com/mcp

</div>

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
• Returns sectionStatus plus warnings so upstream outages are not mistaken for a clean record

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
• Preserves sparse VPIC fields instead of filling missing data with empty placeholders

nhtsa_search_investigations

Search NHTSA defect investigations.

• 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 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
• Accepts either make/model/year or a follow-up vehicleId from earlier NCAP results
• 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
• makes supports limit and offset pagination for the full VPIC catalog
• 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 sparse-field normalization
• Investigation index caching (1h TTL) for fast repeated queries
• No API key required — all NHTSA APIs are public

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.3.2 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

1. Navigate into the directory:

cd nhtsa-vehicle-safety-mcp-server

1. 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 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.