# commutescout

**Category:** 💻 Developer Tools  
**Repository:** https://github.com/nicglazkov/commutescout  
**Views:** 0  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/commutescout

## Description
Live California road conditions: CHP incidents, Caltrans closures, chain controls, and wildfires.

## Claude Desktop Quick Installation
Heuristic fallback — verify the package name and runner against the repository README before running it. Uses `npx` (confidence: low):

```json
"mcpServers": {
  "commutescout": {
    "command": "npx",
    "args": ["-y","commutescout"]
  }
}
```

## Documentation & README

<div align="center">
  <img src="https://raw.githubusercontent.com/nicglazkov/commutescout/HEAD/docs/logo.svg" width="110" alt="CommuteScout logo">
  <h1>CommuteScout</h1>
  <p><b>Live road conditions across 37 states: a map, a route planner, and an
  AI assistant.<br>Also an MCP server, so your assistant can use it too.</b></p>

[![CI](https://github.com/nicglazkov/commutescout/actions/workflows/ci.yml/badge.svg)](https://github.com/nicglazkov/commutescout/actions/workflows/ci.yml)
[![Release](https://img.shields.io/github/v/release/nicglazkov/commutescout?color=2f81f7)](https://github.com/nicglazkov/commutescout/releases)
[![Evals](https://github.com/nicglazkov/commutescout/blob/HEAD/evals/results/badge.svg)](EVALS.md)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)

  <p>
    <a href="https://commutescout.com"><b>Open the app</b></a> ·
    <a href="#add-to-claude">Add to Claude</a> ·
    <a href="#coverage">Coverage</a> ·
    <a href="#self-hosting-advanced">Self-hosting</a> ·
    <a href="https://github.com/nicglazkov/commutescout/blob/HEAD/docs/data-sources.md">Data</a> ·
    <a href="https://github.com/nicglazkov/commutescout/blob/HEAD/docs/mcp.md">MCP tools</a> ·
    <a href="https://github.com/nicglazkov/commutescout/blob/HEAD/docs/architecture.md">Architecture</a>
  </p>

  <p>
    <a href="https://commutescout.com">
      <img src="https://raw.githubusercontent.com/nicglazkov/commutescout/HEAD/docs/try-demo-button.svg" width="230" alt="Open CommuteScout">
    </a>
  </p>
  <p>
    No install, no account:
    <a href="https://commutescout.com"><b>commutescout.com</b></a>
  </p>

  <a href="https://commutescout.com">
    <img src="https://raw.githubusercontent.com/nicglazkov/commutescout/HEAD/docs/demo.gif" width="880"
         alt="Demo: autocompleting San Jose and San Francisco, planning a route with two traffic-colored options, switching between them, tapping a suggested question for a live AI answer, then flashing the statewide live traffic overlay">
  </a>
</div>

CommuteScout reads 53 official agency feeds (CHP dispatch, state DOT
closures and incidents, chain controls, cameras, message signs, wildfire
perimeters, road weather, toll prices) and turns them into one live
picture of the road. Look at the map, plan a route and see what is
actually on it, or ask about a drive in plain English. The same data is
served over [MCP](https://github.com/nicglazkov/commutescout/blob/HEAD/docs/mcp.md), so Claude and other AI assistants can use
it as a tool instead of guessing about traffic.

## What you get

- **A live national map:** incidents by type, closures by class, chain
  controls, wildfires with real burn footprints, roadside weather
  stations, roughly 18,000 traffic cameras, and every message sign
  currently displaying something.
- **Toll and express-lane pricing:** current rates on tolled corridors
  and bridges, drawn along the actual carriageway with hand-verified
  gantry positions, so a price tag never floats over the wrong road.
- **A route planner that knows the roads:** autocomplete, route options,
  turn-by-turn directions, live conditions along the way, and print,
  GPX, KML, or share-link export.
- **An assistant that reads the feeds:** plan a route, tap a suggested
  question, and the answer streams in from the same live data with
  per-source timestamps.
- **Plain-English incident detail:** CHP dispatch logs are translated
  from radio shorthand into readable timelines, with each unit's arrival
  and clearance in order.
- **Watch areas:** draw a circle, polygon, or route corridor and get a
  push or email alert when an incident, closure, chain control, or
  wildfire appears inside it.
- **An MCP server:** ten tools over curated corridors and regions, with
  a [closure taxonomy](https://github.com/nicglazkov/commutescout/blob/HEAD/docs/data-sources.md#the-closure-taxonomy) that
  keeps a closed on-ramp from reading as a closed highway.
- **Public evals:** 91 golden questions on recorded fixtures, scored by
  an LLM judge that is never one of the evaluated models. The
  [scorecard](https://github.com/nicglazkov/commutescout/blob/HEAD/EVALS.md) and its full history are committed to this repo.

<table>
  <tr>
    <td width="34%"><img src="https://raw.githubusercontent.com/nicglazkov/commutescout/HEAD/docs/shots/planner.png" alt="Route planner with two route options, turn-by-turn directions, and suggested questions"><br><sub><b>Plan a trip.</b> Autocomplete, route options, directions, print or export.</sub></td>
    <td width="34%"><img src="https://raw.githubusercontent.com/nicglazkov/commutescout/HEAD/docs/shots/answer.png" alt="An AI answer about a drive, with live speeds and conditions"><br><sub><b>Ask about it.</b> One tap on a suggested question; the answer reads the live feeds.</sub></td>
    <td width="32%"><img src="https://raw.githubusercontent.com/nicglazkov/commutescout/HEAD/docs/shots/map.png" alt="The map with per-layer filters and live counts"><br><sub><b>Or just look.</b> Every layer toggleable, from full closures to blank signs.</sub></td>
  </tr>
</table>

## Coverage

The map covers **37 states**. Coverage is not uniform, because it is
built from what each agency actually publishes: some states offer every
layer keylessly, some publish roadwork only, and a few offer nothing
usable. The map says so directly, shading unsupported states and naming
what is missing rather than showing an empty region.

**California is the deepest.** It is the only state with CHP dispatch
logs, per-lane closure detail, chain-control levels, and CAL FIRE
perimeters. The assistant and the MCP tools answer for every covered
state, but a California question gets that richer detail, while
elsewhere they answer from the normalized state DOT feeds.

Per-state matrix of what is live and why the gaps exist:
**[docs/state-coverage.md](https://github.com/nicglazkov/commutescout/blob/HEAD/docs/state-coverage.md)**. States not yet
integrated, with the reason for each:
**[docs/state-expansion-audit.md](https://github.com/nicglazkov/commutescout/blob/HEAD/docs/state-expansion-audit.md)**.

## Get started

The fastest way to use CommuteScout is the hosted app:
**[commutescout.com](https://commutescout.com)**. Nothing to run, always
on the latest release, feeds already warm.

|  | [commutescout.com](https://commutescout.com) | Self-hosted |
|---|---|---|
| Setup | None, just open it | `pip install` or Cloud Run deploy |
| Updates & feeds | Always current, managed | You redeploy and manage keys |
| AI assistant | Included | Bring your own Anthropic API key |
| Watch-area alerts | Included (invite-only trial) | Extra setup: Firestore, push keys, a scheduler |
| Upcoming premium features | Land here first | Not planned |
| Support | Actively maintained | Best effort via issues |

### Add to Claude

Give Claude live road data with a custom connector:

```
https://mcp.commutescout.com/mcp
```

See it on the site: [commutescout.com/mcp](https://commutescout.com/mcp).
Local stdio setup and the full tool reference: [docs/mcp.md](https://github.com/nicglazkov/commutescout/blob/HEAD/docs/mcp.md).

### Self-hosting (advanced)

Everything here is MIT licensed and the core runs with zero accounts or
keys:

```json
{
  "mcpServers": {
    "commutescout": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/nicglazkov/commutescout", "ca-roads-mcp"]
    }
  }
}
```

The web app is `pip install ".[demo]"` then `ca-roads-demo` with an
`ANTHROPIC_API_KEY` in the environment. For your own Cloud Run copy
(small enough for the free tier most months), optional feed keys, map
snapshot publishing, and the watch-areas setup, see
**[docs/deploy.md](https://github.com/nicglazkov/commutescout/blob/HEAD/docs/deploy.md)**.

Self-hosted deployments are supported on a best-effort basis: issues and
PRs are very welcome, but there is no support guarantee for deployments
I do not run.

## The data

CHP incidents and dispatch logs; Caltrans and 30-plus other state DOT
closures, incidents, cameras, message signs, and road weather; chain
controls from California and the Pacific Northwest; WFIGS and CAL FIRE
wildfires with perimeters; NWS alerts; USGS quakes; toll and express
lane pricing; and optional TomTom and 511 SF Bay feeds.

Every response carries per-source `data_as_of` timestamps, and a failing
feed is never silent: the last good data is served, flagged stale, with
the error attached and surfaced all the way to the UI.

Full source table, refresh rates, and the closure taxonomy:
**[docs/data-sources.md](https://github.com/nicglazkov/commutescout/blob/HEAD/docs/data-sources.md)**.

## How good are the answers?

An eval suite scores the assistant against recorded fixtures: four
scenarios (a Sierra storm day, a fire-closure day, a quiet day, and a
byte-for-byte capture of a real fire-season day), 91 golden questions
with ground truth including traps, and an LLM judge that is never an
evaluated model.

Runs are triggered manually rather than on every release. Firing a full
suite on each release turned out to cost more per month than the hosted
assistant serves, so it now runs when a prompt or tool change actually
warrants re-scoring. Every run appends to a committed history file, so
the trend stays public: **[EVALS.md](https://github.com/nicglazkov/commutescout/blob/HEAD/EVALS.md)**.

## Under the hood

Three cleanly layered Python packages sharing one data spine: a feed
layer with stale-while-revalidate caches and parsers that salvage
complete records from truncated feeds, the MCP surface, and the web app.

The map does not boot through the API. A publisher builds the whole
coverage area once per cycle and uploads pre-gzipped snapshots to object
storage behind a CDN, so first paint is an edge-cached static file and no
visitor request waits on a server assembling JSON. A map left open on a
wall monitor keeps updating in place indefinitely.

Diagram and design notes: **[docs/architecture.md](https://github.com/nicglazkov/commutescout/blob/HEAD/docs/architecture.md)**.

## Contributing

PRs welcome. The test suite is fixture-based and runs without network
access. Start with **[CONTRIBUTING.md](https://github.com/nicglazkov/commutescout/blob/HEAD/CONTRIBUTING.md)**, and see
[adding a data source](https://github.com/nicglazkov/commutescout/blob/HEAD/docs/adding-a-source.md) if you want to wire up a
new feed.

## License & sustainability

CommuteScout is [MIT licensed](https://github.com/nicglazkov/commutescout/blob/HEAD/LICENSE): the map, the planner, the MCP
server, and every data parser, with no open-core carve-outs. The hosted
app at [commutescout.com](https://commutescout.com) will soon offer
optional premium features (deeper history, more alerts); that is what
funds the servers and keeps the free tier free.

## Disclaimer

Data comes from CHP, Caltrans and the other state DOTs listed in
[docs/state-coverage.md](https://github.com/nicglazkov/commutescout/blob/HEAD/docs/state-coverage.md), plus WFIGS, CAL FIRE,
NWS, and USGS. Not affiliated with any agency. Conditions change faster
than any feed; verify before you drive (511 or your state DOT, and
[quickmap.dot.ca.gov](https://quickmap.dot.ca.gov) in California).

Map tiles, routing, and place-name lookup come from Stadia Maps (data
(c) OpenStreetMap contributors), so that service sees the coordinates
involved. Fonts and map libraries are served locally.