vin-decode-mcp

Decode VINs and query vehicle data from a curated NHTSA vPIC database — powered by the Model Context Protocol.

A standalone, offline-capable MCP server for LLMs to decode Vehicle Identification Numbers (VINs) and look up makes, models, and vehicle specifications using data from NHTSA's vPIC.

pip install vin-decode-mcp
vin-decode-mcp  # Start the MCP server

Why?

• Offline: Works without internet access. The curated SQLite database (~4.5 MB) is self-contained.
• No rate limits: Unlike calling the vPIC API directly, local queries are unlimited.
• Fast: Pattern matching against the SQLite database takes microseconds.
• LLM-native: Tools with rich docstrings, schema resources, and structured JSON output.
• Open data: NHTSA vPIC is US government open data — free, no API key required.

Data Coverage

• US-market vehicles, model year 1981 and forward
• 536 makes, 9,284 models, 88,267 VIN patterns (2026-08 vintage)
• Passenger Cars, Trucks, MPVs, Motorcycles, Off-Road Vehicles
• Excludes: Buses, Trailers, Low-Speed Vehicles, Incomplete Vehicles

Specifications only — this database does not include title, accident, odometer, or theft history (those require NMVTIS/commercial data sources).

Quick Start

Installation

pip install vin-decode-mcp

Or from source:

git clone https://github.com/<org>/vin-decode-mcp.git
cd vin-decode-mcp
pip install -e .

Running

# Default: stdio transport (for Claude Desktop, Cursor, etc.)
vin-decode-mcp

# HTTP transport
vin-decode-mcp --transport http --port 8765

Using with Claude Desktop

Create a dedicated venv so the binary lands where you can reference it:

python3 -m venv ~/.local/venvs/vin-decode
source ~/.local/venvs/vin-decode/bin/activate
pip install vin-decode-mcp
deactivate

Add to ~/.config/claude-desktop/config.json (or ~/Library/Application Support/claude-desktop/config.json on macOS):

{
  "mcpServers": {
    "vin-decode": {
      "command": "~/.local/venvs/vin-decode/bin/vin-decode-mcp"
    }
  }
}

Replace the path with wherever you put the venv. Restart Claude Desktop. The model can now use VIN decoding tools in conversations.

Note: Claude Desktop spawns processes with a minimal $PATH that doesn't include conda environments or virtualenvs, so always use the absolute path to the binary — just putting "vin-decode-mcp" won't work.

Available Tools

Tool	Description
decode_vin(vin, model_year?)	Decode a VIN → make, model, year, vehicle type
decode_partial_vin(pattern, limit?)	Match a partial VIN with * wildcards
get_all_makes()	List all vehicle makes
get_models_for_make(make, vehicle_type?)	List models for a make
get_model_years(make, model)	Get production year range
get_wmi_info(wmi)	Decode a WMI → manufacturer info
get_vehicle_types()	List available vehicle types
get_make_vehicle_types(make)	List vehicle types for a make

Examples

>>> decode_vin("1HGCM82633A004352")
{
  "vin": "1HGCM82633A004352",
  "make": "Honda",
  "model": "Accord",
  "year": 2003,
  "vehicle_type": "Passenger Car",
  "wmi": "1HG",
  "confidence": "full"
}

>>> get_model_years("Porsche", "911")
{"year_from": 1981, "year_to": null}

>>> decode_partial_vin("5UXWX7C5*BA")
[{"make": "BMW", "model": "X3", "year": 2011,
  "vehicle_type": "Passenger Car", "confidence": "partial_match"}]

Database

Download

The compiled database is hosted on Hugging Face:

Dataset: https://huggingface.co/datasets/joakes90/vpic-database Direct download: https://huggingface.co/datasets/joakes90/vpic-database/resolve/main/curated_vpic.db

Custom Database Path

# Set via environment variable
export VIN_MCP_DB_PATH=/path/to/curated_vpic.db
vin-decode-mcp

# Or via CLI flag
vin-decode-mcp --db-path /path/to/curated_vpic.db

Rebuilding

The database is rebuilt from NHTSA's standalone PostgreSQL databases approximately every 6-12 months:

# Requires PostgreSQL installed (pg_restore, psql)
bash tools/rebuild.sh

# Or step by step:
# 1. Download NHTSA data: https://vpic.nhtsa.dot.gov/Downloads/
# 2. Convert to SQLite
python3 tools/convert_to_sqlite.py --input dump.sql --output tools/out/vpic_lite.db
# 3. Build curated database
python3 tools/build_db.py --source tools/out/vpic_lite.db --output tools/out/curated_vpic.db

See docs/hf-setup.md for Hugging Face setup instructions.

Data Source & Attribution

Vehicle data sourced from NHTSA's vPIC — the National Highway Traffic Safety Administration's Vehicle Product Information Catalog and Vehicle Listing. NHTSA is a United States government agency.

• Data license: US Government work (public domain)
• API: No key or registration required
• Refresh frequency: ~6-12 months
• Report errors: Contact the NHTSA Manufacturer Helpdesk at manufacturerinfo@dot.gov or 1-888-399-3277

Architecture

User / LLM Agent
       │
       ▼  MCP (stdio / HTTP)
┌──────────────────┐
│  vin-decode-mcp  │  pip install vin-decode-mcp
│  (FastMCP server)│  env: VIN_MCP_DB_PATH=/path/to/curated_vpic.db
└────────┬─────────┘
         │  sqlite3 (mode=ro)
         ▼
┌──────────────────────┐
│  curated_vpic.db     │  ~4.5 MB, curated
│    (Hugging Face)    │  makes + models + WMI + VIN patterns
└──────────────────────┘
         ▲
         │  rebuilds from
┌──────────────────┐
│ NHTSA vPIC PG DB │  69 MB, official
│ (NHTSA website)  │  refreshed 2x/year
└──────────────────┘

Project Structure

vin-decode-mcp/
├── src/vin_decode_mcp/
│   ├── __init__.py              # Package init
│   ├── server.py                # FastMCP server with all tools
│   ├── database.py              # SQLite layer + VIN decoder
│   └── cli.py                   # CLI entry point
├── tools/
│   ├── build_db.py              # Pipeline orchestrator
│   ├── convert_to_sqlite.py     # PG → SQLite converter (COPY text format)
│   ├── vpic_pare_down.py        # Curated pare-down + VIN decode tables
│   ├── rebuild.sh               # Full rebuild script
│   ├── curation.json            # Make/model curation rules
│   ├── overlay.json             # Grey-import classic additions
│   └── README.md                # Rebuild instructions
├── tests/
│   ├── conftest.py              # Test fixtures
│   ├── test_decode.py           # VIN decode canary + regression tests
│   ├── test_server.py           # Bulk lookup tests
│   ├── test_convert.py          # PostgreSQL COPY decoding tests
│   ├── test_real_db.py          # Smoke tests against the curated DB
│   └── fixtures/
│       ├── build_test_db.py     # Test database builder
│       └── test_vpic.db         # Minimal test database
├── .github/workflows/
│   ├── ci.yml                   # CI: test + lint
│   └── rebuild-db.yml           # Scheduled DB rebuild
├── docs/
│   └── hf-setup.md              # Hugging Face setup guide
├── pyproject.toml
├── LICENSE
└── README.md

Development

# Install dev dependencies
pip install -e ".[dev]"

# Run tests
python -m pytest tests/ -v

# Lint
python -m ruff check src/ tests/

# Format
python -m ruff format src/ tests/

Comparison with Other Solutions

	vin-decode-mcp	NHTSA vPIC API	vin-mcp (NLMA)
Transport	Local SQLite	HTTP REST	HTTP REST
Offline	✅	❌	❌
Rate limited	No	Yes	Yes
Data size	~4.5 MB	N/A	N/A
VIN fields	Make + Model + Year	~130 fields	~130 fields
Makes/Models	✅ 536/9,284	✅ Full catalog	✅ Full catalog
Install	pip install	None	pip install

License

MIT License — Code is MIT. Data is US Government public domain.

See LICENSE for details.

Contributing

Contributions welcome! Please:

1. Fork and create a feature branch
2. Add tests for new functionality
3. Ensure CI passes
4. Submit a pull request

For major changes, open an issue first to discuss the approach.