VAHAN Data

VAHAN Data

Scrape India's national vehicle registration database (VAHAN Dashboard) and serve it as a Model Context Protocol (MCP) server — queryable by Claude and any MCP-compatible client.

Data coverage

• 35 states / union territories
• 1,551 Regional Transport Offices (RTOs)
• Year-wise registrations, transactions, revenue, and permits (All India)
• Vehicle class × fuel type breakdown (273,852 rows)
• Vehicle class × emission norms breakdown (205,801 rows)
• Maker/brand-wise registration counts (~1,457 manufacturers per year)
• Historical data from 1970 to present

Table of Contents

1. Setup
2. Scraping
   • scraper.py — dashboard metrics
   • scrape_vehicle_types.py — fuel & norms
   • scrape_makers.py — brand registrations
3. MCP Server
   • stdio transport (local)
   • HTTP transport (web)
4. Hosting with Cloudflared
   • Quick tunnel (no account)
   • Named tunnel (stable URL)
5. Connecting Claude Desktop
6. MCP Tools Reference
7. MCP Resources Reference
8. Database Schema
9. Output Files
10. State Codes
11. Data Caveats

1. Setup

Requirements: Python 3.11+, Node.js (for mcp-remote / Claude Desktop), Homebrew (macOS, for cloudflared)

# Clone / enter the project directory
cd vahandata

# Create virtual environment
python3 -m venv .venv

# Install Python dependencies
.venv/bin/pip install playwright>=1.44.0 pandas>=2.2.0 openpyxl mcp uvicorn starlette

# Install Playwright browsers (needed for scraping only)
.venv/bin/playwright install chromium

2. Scraping

Run the scrapers before starting the MCP server. Scraped data is written to data/ as CSV files, which the server ingests automatically into db/vahan.db on first start.

scraper.py — dashboard metrics

Scrapes year-wise registrations, transactions, revenue, permits, and the RTO list.

# Quick run — state-level data only (~5 min)
.venv/bin/python3 scraper.py --skip-rto

# Full run — includes per-RTO year-wise data (~30–60 min)
.venv/bin/python3 scraper.py

Output files:

scrape_vehicle_types.py — fuel & norms

Scrapes vehicle class breakdowns by fuel type and emission norms across all states.

# Full scrape — all states, fuel + norms (~25 min)
.venv/bin/python3 scrape_vehicle_types.py

# All India totals only — faster (~10 min)
.venv/bin/python3 scrape_vehicle_types.py --all-india-only

# Skip individual sections
.venv/bin/python3 scrape_vehicle_types.py --skip-fuel
.venv/bin/python3 scrape_vehicle_types.py --skip-norms
.venv/bin/python3 scrape_vehicle_types.py --skip-year

Output files:

scrape_makers.py — brand registrations

Scrapes maker/manufacturer-wise vehicle registration counts via XLSX download from the dashboard.

# All India totals, default years (2023–2025)
.venv/bin/python3 scrape_makers.py --all-india-only

# Specific years
.venv/bin/python3 scrape_makers.py --all-india-only --years 2025 2024

# Full run — all 37 states × specified years
.venv/bin/python3 scrape_makers.py --years 2025 2024 2023

Output files:

Sample data (top 10 makers, 2025 All India):

3. MCP Server

mcp_server.py reads the scraped CSVs, builds a SQLite database (db/vahan.db) on first run, and exposes the data as MCP tools and resources.

.venv/bin/python3 mcp_server.py [--transport {stdio|http}] [--host HOST] [--port PORT]

stdio transport (local)

Default mode — launched by Claude Desktop directly over stdin/stdout. No network port opened.

.venv/bin/python3 mcp_server.py
# or explicitly:
.venv/bin/python3 mcp_server.py --transport stdio

HTTP transport (web)

Runs a Streamable HTTP server. MCP endpoint: http://<host>:<port>/mcp

# Bind to all interfaces (public VPS)
.venv/bin/python3 mcp_server.py --transport http

# Bind to localhost only (behind a reverse proxy or cloudflared)
.venv/bin/python3 mcp_server.py --transport http --host 127.0.0.1

# Custom port
.venv/bin/python3 mcp_server.py --transport http --host 127.0.0.1 --port 9000

4. Hosting with Cloudflared

Cloudflare Tunnel exposes the local HTTP server to the public internet without opening firewall ports.

Install cloudflared (macOS):

brew install cloudflared

The convenience script start.sh starts both the MCP server and the tunnel together.

Quick tunnel (no account)

No login required. Gives a random *.trycloudflare.com URL — valid until the process stops.

./start.sh

Example output:

Starting VAHAN MCP server on http://127.0.0.1:8000/mcp ...
MCP server running (PID 12345)
Starting quick tunnel (no login required) ...

+-----------------------------------------------------------------------------------+
|  Your quick Tunnel has been created! Visit it at:                                 |
|  https://male-steve-surgeons-airline.trycloudflare.com                            |
+-----------------------------------------------------------------------------------+

The URL changes every time. For a stable URL use a named tunnel.

Named tunnel (stable URL)

One-time setup (requires a Cloudflare account):

# 1. Log in (opens browser)
cloudflared tunnel login

# 2. Create the tunnel (run once — saves credentials to ~/.cloudflared/)
cloudflared tunnel create vahan

# 3. Optional: route a custom domain
cloudflared tunnel route dns vahan mcp.yourdomain.com

Then start with:

./start.sh --named vahan

start.sh auto-generates ~/.cloudflared/vahan.yml on first run:

tunnel: vahan
credentials-file: ~/.cloudflared/vahan.json

ingress:
  - service: http://localhost:8000

5. Connecting Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json.

Option A — stdio (local, no internet)

{
  "mcpServers": {
    "vahan": {
      "command": "/path/to/vahandata/.venv/bin/python3",
      "args": ["/path/to/vahandata/mcp_server.py"]
    }
  }
}

Option B — remote HTTP via mcp-remote

{
  "mcpServers": {
    "vahan": {
      "command": "npx",
      "args": ["mcp-remote", "https://your-tunnel-url.trycloudflare.com/mcp"]
    }
  }
}

mcp-remote is a client-side bridge that lets Claude Desktop (stdio-only) connect to remote Streamable HTTP MCP servers. It requires Node.js / npx.

Restart Claude Desktop after editing the config. The vahan tools will appear in the tool picker.

6. MCP Tools Reference

get_registrations

Get year-wise All India vehicle counts for a metric.

Note: The VAHAN dashboard only exposes All India totals in its year-wise tables. All state codes hold identical All India values. Use state_code="-1" for the canonical row.

Example:

get_registrations(metric="registrations", state_code="-1", year="2025:")

get_vehicle_class_by_fuel

Get vehicle class registration counts broken down by fuel type for a state.

Returns one row per (vehicle_class, fuel_type) combination, sorted by count descending.

Example:

get_vehicle_class_by_fuel(state_code="MH", fuel_type="PURE EV")

get_vehicle_class_by_norms

Get vehicle class registration counts broken down by emission norm for a state.

Example:

get_vehicle_class_by_norms(state_code="-1", norm="BS VI")

get_yearly_trend

Get the All India year-wise trend for a metric with growth percentages.

Example:

get_yearly_trend(metric="registrations", limit=10)

get_ev_breakdown

Get electric vehicle (EV) registration breakdown.

Covers four EV fuel types: PURE EV, PLUG-IN HYBRID EV, STRONG HYBRID EV, ELECTRIC(BOV).

Examples:

# EV registrations ranked by state
get_ev_breakdown(group_by="state", limit=36)

# EV breakdown by vehicle class in Karnataka
get_ev_breakdown(state_code="KA", group_by="vehicle_class")

# EV sub-type breakdown (pure EV vs hybrid etc.)
get_ev_breakdown(group_by="fuel_type")

search_rtos

Look up Regional Transport Offices (RTOs) by state or name.

Examples:

search_rtos(state_code="MH")
search_rtos(name_contains="bangalore")
search_rtos(state_code="DL", limit=100)

get_top_makers

Get top vehicle manufacturers/brands ranked by registration count.

Data covers ~1,457 makers across all states and years 2024–2026.

Examples:

# Top 10 brands in India for 2025
get_top_makers(state_code="-1", year="2025", limit=10)

# Top makers in Maharashtra
get_top_makers(state_code="MH", year="2025")

search_makers

Search vehicle manufacturers/brands by name substring.

Examples:

# Find all Tata brands
search_makers(name_contains="tata")

# Search Hero brands in All India 2025
search_makers(name_contains="hero", state_code="-1", year="2025")

run_sql

Run an arbitrary read-only SELECT query directly against the SQLite database.

Important query notes:

• yearly_metrics.year uses format "2025:" (calendar year with trailing colon) or "Till Today".
• norms.norm uses spaces: "BS VI", "BS IV" (not "BS-VI").
• The fuel and norms tables store each (vehicle_class, fuel_type/norm) row once per vehicle_group (10 copies). Always deduplicate with MAX(count) GROUP BY (vehicle_class, fuel_type) or MAX(count) GROUP BY (vehicle_class, norm).

Example:

SELECT vehicle_class, MAX(count) AS count
FROM fuel
WHERE state_code = '-1' AND fuel_type = 'PURE EV'
GROUP BY vehicle_class
ORDER BY count DESC
LIMIT 20

7. MCP Resources Reference

Resources are read-only reference data, fetched with resources/read.

8. Database Schema

SQLite database at db/vahan.db. Auto-built from CSVs on first server start.

-- Year-wise All India metrics
-- Note: all state_code values hold All India totals (VAHAN dashboard limitation)
CREATE TABLE yearly_metrics (
    state_code TEXT,
    state_name TEXT,
    year       TEXT,   -- e.g. "2025:", "2024:", "Till Today"
    metric     TEXT,   -- "registrations" | "transactions" | "revenue" | "permits"
    count      INTEGER,
    growth_pct REAL,
    PRIMARY KEY (state_code, year, metric)
);

-- Vehicle class × fuel type, per state
-- Each (vehicle_class, fuel_type) row appears 10× (once per vehicle_group) — use MAX(count) GROUP BY to deduplicate
CREATE TABLE fuel (
    state_code    TEXT,
    state_name    TEXT,
    vehicle_group TEXT,
    vehicle_class TEXT,
    fuel_type     TEXT,
    count         INTEGER
);

-- Vehicle class × emission norm, per state
-- Same 10× duplication as fuel table
CREATE TABLE norms (
    state_code    TEXT,
    state_name    TEXT,
    vehicle_group TEXT,
    vehicle_class TEXT,
    norm          TEXT,   -- e.g. "BS VI", "BS IV" (spaces, not hyphens)
    count         INTEGER
);

-- Regional Transport Offices
CREATE TABLE rtos (
    state_code TEXT,
    state_name TEXT,
    rto_code   TEXT PRIMARY KEY,
    rto_name   TEXT
);

-- States / Union Territories
CREATE TABLE states (
    state_code TEXT PRIMARY KEY,
    state_name TEXT
);

-- Maker/brand registrations per state and year
CREATE TABLE makers (
    state_code TEXT,
    state_name TEXT,
    maker      TEXT,   -- e.g. "HERO MOTOCORP LTD", "MARUTI SUZUKI INDIA LTD"
    year       TEXT,   -- e.g. "2025" (no trailing colon, unlike yearly_metrics)
    count      INTEGER
);

9. Output Files

All files are written to data/.

10. State Codes

11. Data Caveats

Year-wise data is All India only.The VAHAN dashboard's state selector does not update the year-wise data tables — they always display All India totals regardless of which state is selected. The yearly_metrics table stores state codes but all rows contain identical All India values. Use state_code="-1" to get the canonical row.

fuel and norms tables have 10× row duplication.VAHAN's Tabular Summary cross-tab ignores the vehicle_group selection and returns all vehicle classes for every group. Each (vehicle_class, fuel_type, count) combination is stored 10 times (once per vehicle_group). All built-in tools handle this automatically. If writing raw SQL, always use:

MAX(count) GROUP BY vehicle_class, fuel_type   -- for fuel table
MAX(count) GROUP BY vehicle_class, norm        -- for norms table

Year format has a trailing colon.Years are stored as "2025:", "2024:" etc. (with a trailing colon, matching the raw VAHAN output). The special value "Till Today" is the all-time cumulative total.

Emission norm values use spaces not hyphens.Use "BS VI" and "BS IV", not "BS-VI" or "BS-IV".

20 rows of missing norms data for Ladakh / TRAILER.The VAHAN server returns fallback VCG data instead of norms for Ladakh's TRAILER category. These 20 rows (0.01% of the norms table) are a server-side limitation and cannot be resolved by re-scraping.

Maker data is aggregate per year (not month-wise).The XLSX download from the Vahan dashboard provides total registration counts per maker per year. Month-wise and fuel-wise breakdowns are not available in the download export. The data covers all vehicle categories combined (not split by vehicle group).