nhtsa-mcp-connector 1.0.2

MCP server providing 5 tools for querying U.S. vehicle data from NHTSA APIs (VIN decode, recalls, complaints, safety ratings)

NHTSA MCP Connector

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.)
• Ollama support — Included bridge script to use with local LLMs via Ollama

---

Compatibility

Requirement	Supported
Python	>= 3.10 (3.10, 3.11, 3.12, 3.13, 3.14)
Operating System	OS Independent (Windows, macOS, Linux)
MCP Clients	Claude Desktop, Claude Code, Cursor, and any MCP-compatible host
Ollama	Any tool-calling model (llama3.1, mistral, qwen2.5, 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)

pip install nhtsa-mcp-connector

From source

git clone https://github.com/sathiskumarjothi0-oss/nhtsa-mcp-connector.git
cd nhtsa-mcp-connector
pip install .

---

Configuration

Claude Code (CLI / Desktop App)

Run this command to add the NHTSA connector:

claude mcp add nhtsa -- nhtsa-mcp-connector

Or manually add to ~/.claude/settings.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

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

Using uvx (no install needed)

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

Using pip + python

{
  "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 am considering buying this car."

Calls full_vehicle_report - Returns: combined decode + recalls + complaints + safety ratings (fetched in parallel)

---

Testing

Run standalone

nhtsa-mcp-connector

Test with MCP Inspector

npx @modelcontextprotocol/inspector nhtsa-mcp-connector

---

Using with Ollama (Local LLMs)

Ollama does not natively support MCP, but this project includes a bridge script (ollama_bridge.py) that connects Ollama tool-calling models to the NHTSA tools directly.

How It Works

+----------------+    tool calls     +-------------------+     HTTP      +----------------+
|  Ollama        | <---------------> |  ollama_bridge.py | <----------> |  NHTSA APIs    |
|  (llama3.1)    |   function call   |                   |   REST/JSON   |  (public)      |
+----------------+                   +-------------------+               +----------------+

1. User types a question in the terminal
2. Ollama model decides which NHTSA tool to call
3. Bridge executes the tool (calls NHTSA API directly)
4. Result is fed back to the model for a natural language response

Prerequisites

# Install Ollama: https://ollama.com/download
ollama pull llama3.1
pip install ollama requests

Supported Models

Any Ollama model with tool-calling support:

• llama3.1 (recommended)
• llama3.3
• mistral
• qwen2.5
• command-r

Quick Start

# Make sure Ollama is running
ollama serve

# Run the bridge (defaults to llama3.1)
python ollama_bridge.py

Change the Model

Edit the OLLAMA_MODEL variable at the top of ollama_bridge.py:

OLLAMA_MODEL = "mistral"  # or "qwen2.5", "llama3.3", etc.

Example Session

============================================================
  NHTSA Vehicle Intelligence (via Ollama - llama3.1)
  Tools: decode_vin, get_recalls_by_vin, get_complaints,
         get_safety_ratings, full_vehicle_report
============================================================
  Type 'quit' to exit

You: What car is VIN 1HGCM82633A004352?

  [Tool Call] decode_vin({"vin": "1HGCM82633A004352"})
  [Tool Result] received (2847 chars)

Assistant: This VIN belongs to a **2003 Honda Accord EX** with a 3.0L V6
engine, 5-speed automatic transmission. Manufactured in Marysville, Ohio.

You: Are there any recalls on this vehicle?

  [Tool Call] get_recalls_by_vin({"vin": "1HGCM82633A004352"})
  [Tool Result] received (1523 chars)

Assistant: Yes, there are 2 recalls for this vehicle:
1. Airbag inflator replacement (Takata recall)
2. Power window switch - potential fire risk

---

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
│   ├── __main__.py      # python -m entry point
│   └── server.py        # MCP server with all 5 tools
├── ollama_bridge.py     # Ollama <-> NHTSA bridge (local LLMs)
├── mcp_server.py        # Backward-compatible entry point
├── pyproject.toml       # Package metadata and dependencies
├── requirements.txt     # Alt dependency file
├── LICENSE              # MIT
└── README.md

MCP Architecture

+--------------------+     MCP Protocol      +----------------------+     HTTP      +----------------+
|  MCP Client        | <---- stdio --------> |  nhtsa-mcp-server    | <----------> |  NHTSA APIs    |
|  (Claude, Cursor)  |   tool calls/results  |  - Pydantic valid.   |   REST/JSON   |  (public)      |
+--------------------+                       |  - 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.

---

Developer Guide — Publishing to PyPI

Prerequisites

pip install build twine

Step 1: Build the package

cd nhtsa-mcp-connector
python -m build

This creates two files in dist/:

• nhtsa_mcp_connector-X.X.X.tar.gz (source)
• nhtsa_mcp_connector-X.X.X-py3-none-any.whl (wheel)

Step 2: Create a PyPI API token

1. Go to https://pypi.org/manage/account/token/
2. Create a new token with scope: "Entire account"

   Important: For a brand-new package that doesn't exist yet on PyPI, project-scoped tokens will NOT work. You must use an "Entire account" scoped token for the first upload. After the first successful upload, you can create a project-scoped token and switch to it.

3. Copy the token — it starts with pypi-...

Step 3: Upload to PyPI

python -m twine upload dist/* --verbose

When prompted:

• Username: __token__
• Password: paste the full token including the pypi- prefix

Alternative — pass credentials inline:

python -m twine upload dist/* --username __token__ --password pypi-YOUR_FULL_TOKEN_HERE

Step 4 (optional): Save credentials for reuse

Create ~/.pypirc so you don't have to paste the token every time:

[pypi]
username = __token__
password = pypi-YOUR_FULL_TOKEN_HERE

Uploading to TestPyPI first (recommended for testing)

python -m twine upload --repository testpypi dist/*

Then test the install:

pip install --index-url https://test.pypi.org/simple/ nhtsa-mcp-connector

Version bumps

Update the version in two places before rebuilding:

1. src/nhtsa_mcp_connector/__init__.py → __version__
2. pyproject.toml → version

Then clean, rebuild, and upload:

rm -rf dist/ build/
python -m build
python -m twine upload dist/*

Troubleshooting

Error	Cause	Fix
403 Forbidden	Token lacks permission	Use an "Entire account" scoped token for first upload
400 File already exists	Same version already uploaded	Bump version in pyproject.toml and __init__.py
401 Unauthorized	Invalid or expired token	Generate a new token at https://pypi.org/manage/account/token/

---

License

MIT https://pypi.org/project/nhtsa-mcp-connector/