NHVR Tools

Python SDK, MCP server, and CLI for Australian heavy vehicle compliance data.

nhvr-tools gives you quick access to fatigue rules, mass limits, dimension limits, Chain of Responsibility duties, accreditation guidance, permits, breach categories, and NHVR registration lookups.

The PyPI package name is nhvr-tools. The Python import path is nhvr_mcp.

Quick Start

Choose the smallest install that matches your use case:

Playwright is optional. Base imports, SDK usage, CLI help, CLI knowledge commands, and MCP server startup work without it.

Install

Install From PyPI

pip install nhvr-tools
pip install "nhvr-tools[cli]"
pip install "nhvr-tools[mcp]"
pip install "nhvr-tools[all]"

Install From Source

git clone https://github.com/MBemera/nhvr-tools.git
cd nhvr-tools
pip install -e ".[dev]"

For a smaller source install:

pip install -e .
pip install -e ".[cli]"
pip install -e ".[mcp]"

Optional Playwright Install

pip install "nhvr-tools[scraper]"
playwright install chromium

If Playwright is missing, scraper-specific commands return a readable install hint instead of crashing.

Claude Desktop And MCP

Recommended Setup

pip install "nhvr-tools[mcp]"
nhvr-setup

nhvr-setup checks the MCP dependency, offers optional API key and Playwright guidance, writes the Claude Desktop config, and verifies that the server imports correctly.

Useful setup commands:

nhvr-setup --help
nhvr-setup --print-config
nhvr-setup --yes --api-key "your-nhvr-api-key"

nhvr-setup is safe in non-interactive shells. If there is no stdin, it prints the config snippet instead of crashing or silently overwriting files.

Manual Claude Desktop Config

Claude Desktop config paths:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

Use the same Python interpreter that has nhvr-tools[mcp] installed:

{
  "mcpServers": {
    "nhvr-tools": {
      "command": "python3",
      "args": ["-m", "nhvr_mcp.server"]
    }
  }
}

If you use registration lookups, add NHVR_API_KEY to the env block.

Run The MCP Server Directly

# stdio transport
python -m nhvr_mcp.server

# HTTP transport
NHVR_MCP_TRANSPORT=streamable_http \
NHVR_MCP_HOST=0.0.0.0 \
NHVR_MCP_PORT=8080 \
python -m nhvr_mcp.server

Available MCP Tools

CLI

Install:

pip install "nhvr-tools[cli]"

Common commands:

nhvr fatigue rules
nhvr fatigue rules --scheme bfm
nhvr mass limits --include-hml
nhvr mass hml
nhvr dimension limits
nhvr breach categories --type mass
nhvr cor duties --role operator
nhvr accreditation --module fatigue
nhvr permits --type oversize
nhvr rego ABC123
nhvr search "rest breaks"
nhvr --format json fatigue rules

Search uses aliases and lightweight fuzzy matching. Queries like bfm, afm, rest breaks, b-double mass, loader duty, executive due diligence, speed limiter, and oversize permits resolve more reliably than plain substring matching. If there is no strong match, the CLI suggests likely topics instead of returning a dead end.

Python SDK

from nhvr_mcp import NHVR

client = NHVR()

fatigue = client.fatigue_rules("bfm")
mass = client.mass_limits(include_hml=True)
dimensions = client.dimension_limits()
cor = client.cor_duties("operator")
permits = client.permit_types("oversize")

Async methods:

import asyncio
from nhvr_mcp import NHVR

client = NHVR(api_key="your-nhvr-api-key")

rego = asyncio.run(client.search_registration("ABC123"))
search = asyncio.run(client.search("b-double mass"))
page = asyncio.run(client.scrape("https://www.nhvr.gov.au/road-access/mass-and-dimension/mass-limits"))

search_registration() needs an NHVR API key. search() and scrape() may use Playwright for live NHVR pages. If live scraping is unavailable, topic search falls back to the built-in knowledge base where possible.

Static knowledge responses include:

• source_title
• source_url
• last_verified
• unofficial_warning

Docker

The default image runs the MCP server with the mcp extra installed. It is intended for MCP clients, not for interactive CLI use.

Build the image:

docker build -t nhvr-tools .

Run MCP Over Stdio

Use stdio mode when the container is attached directly to an MCP client process:

docker run --rm -i nhvr-tools

Run MCP Over HTTP

docker run --rm \
  -p 8080:8080 \
  -e NHVR_MCP_TRANSPORT=streamable_http \
  -e NHVR_MCP_HOST=0.0.0.0 \
  -e NHVR_MCP_PORT=8080 \
  nhvr-tools

Then connect your MCP-capable client to port 8080.

Docker Environment Variables

Docker Note About Scraping

The default image does not install Playwright. That keeps the container smaller and allows MCP startup without browser dependencies. Scraper-specific operations return a clear install hint instead of crashing.

If you need live NHVR scraping inside Docker, extend the image with:

pip install "nhvr-tools[scraper]"
playwright install chromium

You may also need the extra Playwright system packages required by your base image.

Troubleshooting

nhvr-setup printed config instead of writing it

That usually means the command ran without interactive stdin. Run nhvr-setup in a normal terminal, or use nhvr-setup --yes to accept default prompts explicitly.

ModuleNotFoundError: fastmcp

Install the MCP extra:

pip install "nhvr-tools[mcp]"

Scraper command says Playwright is required

Install scraper support and the browser:

pip install "nhvr-tools[scraper]"
playwright install chromium

Registration lookup says an API key is required

Set the environment variable or pass it directly:

export NHVR_API_KEY="your-key"

from nhvr_mcp import NHVR

client = NHVR(api_key="your-key")

Search could not find a topic

Use one of the suggested topics, or scrape a specific NHVR page directly:

nhvr scrape "https://www.nhvr.gov.au/road-access/access-permits"

Development

Install the dev environment:

pip install -e ".[dev]"

Run the local checks:

ruff check .
pytest
python -m build
python -m twine check dist/*

Data Sources

Built-in knowledge is based on official NHVR and HVNL material, including:

• NHVR website
• Heavy Vehicle National Law and regulations
• NHVR developer portal

This project is unofficial. It is not affiliated with or endorsed by the NHVR. Always verify operational and legal requirements against current official sources.

License

MIT