Metadata-Version: 2.4
Name: nhtsa-mcp-connector
Version: 1.0.0
Summary: MCP server providing 5 tools for querying U.S. vehicle data from NHTSA APIs (VIN decode, recalls, complaints, safety ratings)
Project-URL: Homepage, https://github.com/SathiskumarJothi/nhtsa-mcp-connector
Project-URL: Repository, https://github.com/SathiskumarJothi/nhtsa-mcp-connector
Project-URL: Issues, https://github.com/SathiskumarJothi/nhtsa-mcp-connector/issues
Author: Sathiskumar Jothi
License-Expression: MIT
License-File: LICENSE
Keywords: ai,connector,llm,mcp,nhtsa,recalls,safety,vehicle,vin
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.10
Requires-Dist: mcp[cli]>=1.0.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: requests>=2.31.0
Description-Content-Type: text/markdown

# NHTSA MCP Connector

[![PyPI](https://img.shields.io/pypi/v/nhtsa-mcp-connector)](https://pypi.org/project/nhtsa-mcp-connector/)
[![Python](https://img.shields.io/pypi/pyversions/nhtsa-mcp-connector)](https://pypi.org/project/nhtsa-mcp-connector/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

A Model Context Protocol (MCP) server that provides LLMs with access to real-time U.S. vehicle data from official NHTSA (National Highway Traffic Safety Administration) government APIs.

**No API key required** — all NHTSA endpoints are free and public.

### Highlights

- **Pydantic validation** — All tool inputs are validated (VIN format, year range, non-empty fields)
- **Parallel execution** — `full_vehicle_report` fetches recalls, complaints, and ratings concurrently via ThreadPoolExecutor
- **Streaming progress** — Tools report progress via MCP Context for real-time status in supporting clients
- **Standardized interface** — Works with any MCP-compatible client (Claude Desktop, Claude Code, Cursor, etc.)

---

## Tools (5)

| # | Tool | Description |
|---|------|-------------|
| 1 | `decode_vin` | Decode a 17-character VIN into full vehicle specs (make, model, year, engine, transmission, body style, plant info) |
| 2 | `get_recalls_by_vin` | Get all safety recalls for a specific VIN (campaign numbers, descriptions, remedy info) |
| 3 | `get_complaints` | Get consumer complaints filed with NHTSA for a vehicle by make/model/year |
| 4 | `get_safety_ratings` | Get NCAP crash test safety ratings (1-5 stars: overall, frontal, side, rollover) |
| 5 | `full_vehicle_report` | Generate a comprehensive report combining decode + recalls + complaints + ratings from a single VIN |

---

## Installation

### From PyPI (recommended)

```bash
pip install nhtsa-mcp-connector
```

### From source

```bash
git clone https://github.com/SathiskumarJothi/nhtsa-mcp-connector.git
cd nhtsa-mcp-connector
pip install .
```

---

## Configuration

### Claude Code (CLI / Desktop App)

Run this command to add the NHTSA connector:

```bash
claude mcp add nhtsa -- nhtsa-mcp-connector
```

Or manually add to `~/.claude/settings.json`:

```json
{
  "mcpServers": {
    "nhtsa": {
      "command": "nhtsa-mcp-connector"
    }
  }
}
```

### Claude Desktop App

Add to your `claude_desktop_config.json`:

- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`

```json
{
  "mcpServers": {
    "nhtsa": {
      "command": "nhtsa-mcp-connector"
    }
  }
}
```

### Using uvx (no install needed)

```json
{
  "mcpServers": {
    "nhtsa": {
      "command": "uvx",
      "args": ["nhtsa-mcp-connector"]
    }
  }
}
```

### Using pip + python

```json
{
  "mcpServers": {
    "nhtsa": {
      "command": "python",
      "args": ["-m", "nhtsa_mcp_connector.server"]
    }
  }
}
```

---

## Usage Examples

Once configured, ask your AI assistant natural language questions:

### Decode a VIN
```
"What car is VIN 1HGCM82633A004352?"
```
→ Calls `decode_vin` → Returns: 2003 Honda Accord, 3.0L V6, 5-speed automatic, sedan...

### Check Recalls
```
"Are there any recalls on VIN 5YJSA1DN5DFP14705?"
```
→ Calls `get_recalls_by_vin` → Returns: list of recall campaigns with descriptions and remedies

### Get Complaints
```
"What complaints have been filed for the 2020 Toyota Camry?"
```
→ Calls `get_complaints(make="Toyota", model="Camry", model_year=2020)` → Returns: consumer complaints with crash/injury data

### Safety Ratings
```
"How safe is the 2023 Honda Civic in crash tests?"
```
→ Calls `get_safety_ratings(make="Honda", model="Civic", model_year=2023)` → Returns: NCAP star ratings

### Full Vehicle Report
```
"Give me a full report on VIN 1HGCM82633A004352 — I'm considering buying this car."
```
→ Calls `full_vehicle_report` → Returns: combined decode + recalls + complaints + safety ratings (fetched in parallel)

---

## Testing

### Run standalone

```bash
nhtsa-mcp-connector
```

### Test with MCP Inspector

```bash
npx @modelcontextprotocol/inspector nhtsa-mcp-connector
```

---

## Data Sources

All data comes from official U.S. government APIs:

| API | Source |
|-----|--------|
| vPIC (VIN Decode) | https://vpic.nhtsa.dot.gov/api/ |
| Recalls | https://api.nhtsa.gov/recalls |
| Complaints | https://api.nhtsa.gov/complaints |
| Safety Ratings | https://api.nhtsa.gov/SafetyRatings |

---

## Architecture

```
nhtsa-mcp-connector/
├── src/nhtsa_mcp_connector/
│   ├── __init__.py      # Package version
│   └── server.py        # MCP server with all 5 tools
├── mcp_server.py        # Backward-compatible entry point
├── pyproject.toml       # Package metadata & dependencies
├── requirements.txt     # Alt dependency file
├── LICENSE              # MIT
└── README.md
```

### How It Works

```
┌──────────────────┐     MCP Protocol      ┌────────────────────┐     HTTP      ┌──────────────┐
│  MCP Client      │ ◄──── stdio ────────► │  nhtsa-mcp-server  │ ◄──────────► │  NHTSA APIs  │
│  (Claude, Cursor) │   tool calls/results  │                    │   REST/JSON   │  (public)    │
└──────────────────┘                        │  - Pydantic valid. │               └──────────────┘
                                            │  - Parallel exec   │
                                            │  - Progress stream │
                                            └────────────────────┘
```

1. Client sends a tool call (e.g. `decode_vin`) over MCP stdio
2. Server validates input with Pydantic (rejects bad VINs, empty fields, etc.)
3. Server calls NHTSA public APIs, streaming progress back to the client
4. `full_vehicle_report` runs 3 API calls in parallel after the initial VIN decode
5. JSON result is returned to the client

---

## Input Validation

| Field | Rule |
|-------|------|
| `vin` | Exactly 17 alphanumeric chars, no I/O/Q, auto-uppercased |
| `make` | Non-empty string, auto-trimmed |
| `model` | Non-empty string, auto-trimmed |
| `model_year` | Integer between 1900 and 2030 |

Invalid inputs return a clear Pydantic validation error before any API call is made.

---

## Publishing (for maintainers)

```bash
pip install build twine
python -m build
twine upload dist/*
```

---

## License

MIT
