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

• 36 states / union territories (including All India)

• Available for combimations of X-Y axes (year and state level data)

• Available X-Y axes are:

  • X-axis: Fuel, Maker, Vehicle Class, Vehicle Category Group, Norms, Month Wise

  • Y-axis: Fuel, Maker, Vehicle Class, Vehicle Category Group, Norms

Table of Contents

1. Setup

2. Scraping

3. MCP Server

4. Hosting (Direct Domain)

5. Connecting Claude Desktop

6. MCP Tools Reference

7. MCP Resources Reference

8. Database Schema

9. Output Files

10. State Codes

11. Data Caveats

12. Deployment (Custom Domain & SSL)

1. Setup

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

# 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

The project uses a unified Playwright-based scraper to collect data from the VAHAN Dashboard.

vahan_scraper.py — Unified Scraper

The project uses a unified Playwright-based scraper to collect data from the VAHAN Dashboard. It automates selection, extraction, and consolidation of multi-dimensional registration data.

Scraper Usage

--year is the only mandatory parameter. By default, the scraper iterates through multiple X/Y axis combinations and all Indian states.

# Full extraction (Broad defaults: Multiple X/Y combinations, all states)
.venv/bin/python scraping/vahan_scraper.py --year 2025

# Targeted extraction: Maker x Fuel breakdown for specific states
.venv/bin/python scraping/vahan_scraper.py \
  --year 2025 \
  --state "DELHI" "HARYANA" \
  --xaxis "Fuel" \
  --yaxis "Maker"

Naming Scheme: Generated files follow the pattern data/[xaxis]_[yaxis]_[year].csv (e.g., data/Fuel_Maker_2025.csv). Each file contains consolidated registration data across all states.

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)
.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

The server is configured to run behind an Nginx reverse proxy on a custom domain (vahanmcp.shubhamgrg.com).

• Reverse Proxy: Nginx listens on port 80/443 and forwards traffic to 127.0.0.1:8000.

• SSL: Automated via Certbot (Let's Encrypt).

This project includes vahan-mcp.nginx and an automated deploy.sh script to handle the configuration.

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://vahanmcp.shubhamgrg.com/mcp"]
    }
  }
}

6. MCP Tools Reference

get_vahan_metrics

Flexible tool to fetch vehicle registration counts across any combination of dimensions (e.g., Maker, Fuel, Norms, Vehicle Class).

get_top_performers

Identify top values in a dimension (e.g., top makers or fuel types) ranked by registration volume.

search_dimension_values

Search for specific values within a dimension by name substring (e.g., finding a specific manufacturer).

get_ev_stats

Dedicated analysis for Electric Vehicle (EV) registration adoption trends.

search_rtos

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

run_sql

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

Tables:

• vahan_data(yaxis_name, yaxis_value, xaxis_name, xaxis_value, state, year, count)

• rtos(state_code, state_name, rto_code, rto_name)

• states(state_code, state_name)

7. MCP Resources Reference

8. Database Schema

SQLite database at db/vahan.db. Automatically synced from CSVs in data/ on server start using a tracking log.

CREATE TABLE vahan_data (
    yaxis_name  TEXT,    -- e.g. "Maker", "Vehicle Class"
    yaxis_value TEXT,    -- e.g. "TATA MOTORS LTD"
    xaxis_name  TEXT,    -- e.g. "Fuel", "Month Wise"
    xaxis_value TEXT,    -- e.g. "PETROL", "JAN"
    state       TEXT,    -- e.g. "DELHI"
    year        INTEGER, -- e.g. 2025
    count       INTEGER
);

CREATE TABLE ingestion_log (
    filename      TEXT PRIMARY KEY,
    last_modified REAL,
    ingested_at   TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

CREATE TABLE rtos (
    state_code TEXT,
    state_name TEXT,
    rto_code   TEXT PRIMARY KEY,
    rto_name   TEXT
);

CREATE TABLE states (
    state_code TEXT PRIMARY KEY,
    state_name TEXT
);

9. Output Files

All raw scraped data is stored in the data/ directory.

10. State Codes

11. Data Caveats

All India data is captured as a "state" value. When scraping "All India" totals, the result is stored with state name "All India".

Clean Data Transformation. Unlike legacy versions, this scraper performs automatic cleaning and transformation to a standardized long format. Numeric counts are cleaned of commas and non-numeric characters during ingestion.

High Performance Querying. The unified vahan_data table is indexed by category, state, and year for fast retrieval of trends and rankings.

12. Deployment (Custom Domain & SSL)

The project includes built-in automation for deployment to a Digital Ocean droplet using GitHub Actions, Nginx, and Certbot.

Droplet Setup (One-time)

1. DNS Setup: Point vahanmcp.shubhamgrg.com (A record) to your droplet's IP address.

2. Authorize GitHub SSH Key: Add your GitHub Action's public SSH key to /root/.ssh/authorized_keys on your droplet.

3. Setup Folder: The automation expects the project to live at /root/vahandata.

4. Initial Deploy: Push to the main branch.

GitHub Actions (CI/CD)

The .github/workflows/deploy.yml workflow automatically:

• Clones/Pulls the code to /root/vahandata.

• Installs python3-venv, nginx, and certbot if missing.

• Sets up the Python virtual environment and dependencies.

• Configures Nginx and handles SSL (Certbot) for vahanmcp.shubhamgrg.com.

• Manages the vahan-mcp background service.

Service & Proxy Management

# Monitor the MCP Server
systemctl status vahan-mcp
journalctl -u vahan-mcp -f

# Manage Nginx
systemctl status nginx
nginx -t

Automated scraping through github actions don't work as vahan website blocks traffic from github actions. So you need to run the scraper manually.