io.github.cyanheads/nhtsa-vehicle-safety-mcp-server
Decode VINs, search recalls, complaints, crash ratings, and investigations.
Open source Repository Open in the app JSON README (API)
About
Decode VINs, search recalls, complaints, crash ratings, and investigations.
Details
- Kind
- MCP servers
- Topic
- No topic detected
- Publisher
- cyanheads
- Origin
- official
- Category
- ferramentas
- Transport
- http
- Version
- 0.9.5
- Stars
- 1
- Last push
- 2026-08-21T23:18:32Z
- Repository state
- ativo
- Language
- TypeScript
- License
- Apache-2.0
- Added
- 2026-08-29 03:02:39
- Updated
- 2026-08-29 03:02:39
- Origin id
io.github.cyanheads/nhtsa-vehicle-safety-mcp-server
README
<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">
[](./CHANGELOG.md) [](./LICENSE) [](https://github.com/users/cyanheads/packages/container/package/nhtsa-vehicle-safety-mcp-server) [](https://modelcontextprotocol.io/) [](https://www.npmjs.com/package/@cyanheads/nhtsa-vehicle-safety-mcp-server) [](https://www.typescriptlang.org/) [](https://bun.sh/)
</div>
<div align="center">
[](https://github.com/cyanheads/nhtsa-vehicle-safety-mcp-server/releases/latest/download/nhtsa-vehicle-safety-mcp-server.mcpb) [](https://cursor.com/en/install-mcp?name=nhtsa-vehicle-safety-mcp-server&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkBjeWFuaGVhZHMvbmh0c2EtdmVoaWNsZS1zYWZldHktbWNwLXNlcnZlciJdfQ==) [](https://vscode.dev/redirect?url=vscode:mcp/install?%7B%22name%22%3A%22nhtsa-vehicle-safety-mcp-server%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40cyanheads/nhtsa-vehicle-safety-mcp-server%22%5D%7D)
[](https://www.npmjs.com/package/@cyanheads/mcp-ts-core)
</div>
<div align="center">
**Public Hosted Server:** [https://nhtsa.caseyjhand.com/mcp](https://nhtsa.caseyjhand.com/mcp)
</div>
---
## Tools
Seven tools for querying NHTSA vehicle safety data:
| Tool Name | Description |
|:----------|:------------|
| `nhtsa_get_vehicle_safety` | Comprehensive safety profile combining crash test ratings, recalls, and complaint summary with per-section availability status. |
| `nhtsa_search_recalls` | Search recall campaigns by vehicle or campaign number with optional date filtering. |
| `nhtsa_search_complaints` | Consumer safety complaints with component breakdown and severity stats. |
| `nhtsa_get_safety_ratings` | NCAP crash test ratings and ADAS feature availability. |
| `nhtsa_decode_vin` | Decode VINs for make, model, year, engine, safety equipment (single or batch up to 50). |
| `nhtsa_search_investigations` | Search NHTSA defect investigations (PE, EA, DP, RQ, AQ, and more) with cached index. |
| `nhtsa_lookup_vehicles` | Look up valid makes, models, vehicle types, and manufacturer details from VPIC. |
### `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
- Recall consequence text plus the do-not-drive, park-outside, and over-the-air-update advisories
- 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
- Campaign lookups return every make/model the campaign covers, plus the ODI investigation that preceded it
- 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 investigation IDs, subjects, and summaries, plus structured make, model, and component filters
- `nhtsaId` fetches one investigation by its exact ID — the reverse of the recall link, closing the campaign-to-investigation round trip
- Sourced from NHTSA's ODI bulk file (`FLAT_INV.zip`) — the first query downloads and parses it (~10s), subsequent queries use the cached index (24h TTL, matching the file's daily refresh)
- Returns up to 25 investigations per page; the response echoes `offset`/`limit` and the offset for the next page
---
### `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
- An incident date 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`
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
- `manufacturer` pages VPIC up to a 500-record ceiling and discloses when a broad partial name hits it
## Features
Built on [`@cyanheads/mcp-ts-core`](https://github.com/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 four NHTSA JSON APIs with retry logic and sparse-field normalization, plus a streaming parser for the ODI investigations bulk file
- Investigation index caching (24h 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:
```json
{
"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:
```json
{
"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):
```json
{
"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:
```json
{
"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:
```sh
MCP_TRANSPORT_TYPE=http MCP_HTTP_PORT=3010 bun run start:http
# Server listens at http://localhost:3010/mcp
```
### Prerequisites
- [Bun v1.3.2](https://bun.sh/) or higher (or Node.js >= 24.0.0)
### Installation
1. **Clone the repository:**
```sh
git clone https://github.com/cyanheads/nhtsa-vehicle-safety-mcp-server.git
```
2. **Navigate into the directory:**
```sh
cd nhtsa-vehicle-safety-mcp-server
```
3. **Install dependencies:**
```sh
bun install
```
## Configuration
No API keys required — all NHTSA APIs are public.
| Variable | Description | Default |
|:---------|:------------|:--------|
| `MCP_TRANSPORT_TYPE` | Transport: `stdio` or `http`. | `stdio` |
| `MCP_HTTP_HOST` | HTTP server host. | `127.0.0.1` |
| `MCP_HTTP_PORT` | HTTP server port. | `3010` |
| `MCP_HTTP_ENDPOINT_PATH` | HTTP endpoint path. | `/mcp` |
| `MCP_AUTH_MODE` | Auth mode: `none`, `jwt`, or `oauth`. | `none` |
| `MCP_LOG_LEVEL` | Log level (RFC 5424). | `info` |
## 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`
- **Safety Ratings API** — `api.nhtsa.gov/SafetyRatings`
- **Investigations bulk file** — `static.nhtsa.gov/odi/ffdd/inv/FLAT_INV.zip`
- **VPIC API** — `vpic.nhtsa.dot.gov/api/vehicles`
## Running the server
### Local development
```sh
bun run devcheck # Lints, formats, type-checks, and more
bun run test # Runs the test suite
```
### Production
```sh
bun run build
bun run start:stdio # Production stdio
bun run start:http # Production HTTP
```
### Docker
```sh
docker build -t nhtsa-vehicle-safety-mcp-server .
docker run -p 3010:3010 nhtsa-vehicle-safety-mcp-server
```
## Project structure
| Directory | Purpose |
|:----------|:--------|
| `src/index.ts` | Server entry point — `createApp()` registration. |
| `src/mcp-server/tools/definitions/` | Tool definitions (`*.tool.ts`). |
| `src/services/nhtsa/` | NHTSA API client and ODI bulk-file parser with field normalization. |
## Development guide
See [`CLAUDE.md`](./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:
```sh
bun run devcheck
bun run test
```
## License
Apache-2.0 — see [LICENSE](LICENSE) for details.