DMV Regional Transportation Assistant (transit-mcp)

A plain-language assistant that helps people — especially first-time riders — get around the Washington DC / Maryland / Virginia region by public transit. It answers from current, cited data pulled from WMATA (Metrorail + Metrobus), the Virginia systems (VRE, Fairfax Connector, ART, DASH, CUE, Loudoun, OmniRide, Virginia Breeze), Maryland (MTA bus, commuter bus, Metro SubwayLink, Light RailLink, MARC, Annapolis Transit, Harbor Connector, Potomac Valley), the Dulles Airport shuttles, and intercity services (Amtrak, FlixBus and other intercity buses), and focuses on what trips actually hinge on: which systems connect where, on which days and at what times a connection works, and how to pay each leg.

The home page is a leave-now trip planner on a map: type where you're going (or use your location), and it shows every good way to get there in the next 3 hours — direct trips first, one change only when it saves time, and changes with a wait of 10 minutes or less preferred (a longer wait is offered only when nothing better works) — with live departure times where the agency publishes them. It uses each agency's closest stops (up to about a mile away) and shows how much walking each trip involves. The assistant chat sits in a drawer beside the map.

Unofficial. This is an independent project. It is not affiliated with, endorsed by, sponsored by, or operated by WMATA or any other transit agency. Agency names identify their services only. For official information, contact the agency directly.

Answers are grounded in the stored data: the assistant must call its tools before it answers, is instructed never to fill gaps from the model's general knowledge, and says "I don't have that information" rather than guess. (The Claude API no longer accepts a temperature setting, so accuracy is enforced through the data, the tools and the prompt instead — see chat/agent.py.)

Quick start (Windows)

1. Install Python 3.11+ (tick Add python.exe to PATH).
2. Double-click start.bat.
   • First time: it sets everything up, creates a settings file and opens it in Notepad. Paste in your ANTHROPIC_API_KEY (console.anthropic.com) and WMATA_API_KEY (free at developer.wmata.com), save, and double-click start.bat again. It then downloads transit data (15–20 minutes for all 23 feeds).
   • For the map planner, also add TRANSITLAND_API_KEY (transit.land, Explorer plan) and GOOGLE_GEOCODING_API_KEY (Google Geocoding API; GEOCODE_API_KEY from geocode.maps.co also works), and download the regional map once (about 600 MB; without it the map shows a plain background): powershell -ExecutionPolicy Bypass -File deploy\map\fetch-basemap.ps1
   • After that: the assistant opens in your web browser within seconds.
3. Keep the black window open while you use it; close it to stop.

File	What it does
start.bat	Set up if needed, then start the assistant and open the browser
refresh-data.bat	Download the latest alerts, schedules, fares and rider info (run weekly)
check-setup.bat	Plain-English check of keys, data, agencies and the trip planner

If a feed can't be downloaded, you can add it by hand — see feeds/README.md.

Deploying (public website)

The same app runs as a public site — https://dmvtransit.com — on one small AWS Lightsail server in Ohio (us-east-2) with Docker, created and managed by the scripts in deploy/lightsail/: docker compose up -d --build starts the website, automatic HTTPS (Caddy) and a scheduler that keeps data fresh. Public mode adds per-visitor rate limits, a site-wide daily cap and friendly error messages. Step-by-step guide: deploy/README.md.

Architecture

Three layers, each swappable on its own (details in docs/EXTENDING.md):

 agencies/*.toml ──► ingest source plugins ──► SQLite (FTS5) + data/gtfs/*.zip
 one file per         gtfs · web_pages ·              │
 agency               wmata_api · (yours)             ▼
                                         retrieval + scheduling engine
                                         heuristic | python | process | http
                                                      │  TripRequest / TripPlan
                                                      ▼
                                   MCP server (17 tools) ──► web chat (Claude)
                                                         └─► any MCP client

Layer	Extension point	Where
Agencies	Drop a TOML file — no code	agencies/, built-ins in src/transit_mcp/agencies/definitions/
Data sources	@register_source plugin or entry point	src/transit_mcp/ingest/sources/
Trip planning	Your engine in Python, Node (stdio) or HTTP behind a versioned JSON contract	src/transit_mcp/planning/, templates in engines/

Every stored record keeps its source URL, fetch time and content hash, so answers are cited and stale data is flagged.

Where each kind of answer comes from

Answer	Source
Routes, stops, schedules, service days and hours (Metrorail and Metrobus included)	Each agency's GTFS feed, found through Transitland
Fares, how to pay, how to ride	The agency's own fare / rider web pages, plus WMATA's station-to-station fare data (checked against wmata.com/pay.html)
Disruptions	WMATA real-time incidents, agencies' GTFS-realtime alerts, and their service-alert / service-change web pages — always shown alongside the GTFS schedule, never instead of it
Live departure times (map planner)	The agency's own GTFS-realtime TripUpdates feed at the URL Transitland lists (WMATA rail and bus, VRE, Fairfax Connector, MARC, ART); Transitland's departures API for the rest. Otherwise scheduled times, labelled "Scheduled"
Addresses → map points	Suggestions while typing from Google Places Autocomplete (place picked → Place Details for its location), else the Google Geocoding API (or geocode.maps.co without a Google key); all called from the server (the key never reaches browsers)
The map	OpenStreetMap data in a self-hosted Protomaps extract, drawn with MapLibre GL

Web pages are never used for routes or schedules. Each feed is downloaded from the official URL listed in Transitland's public registry (no API quota used); Transitland's own hosted copy is the fallback, at one metered API call each (transit-mcp doctor shows which source each feed used). Every Transitland API call is counted against TRANSITLAND_MONTHLY_BUDGET (4,500 of the Explorer plan's 5,000), after which the planner shows scheduled times.

The planner only suggests a change between two stops less than 0.3 km apart (of any agency), so every transfer is a short walk. Trips with two changes are searched only when nothing with fewer changes works (TRIP_MAX_TRANSFERS). At BWI, DCA and IAD the step between the terminal and the rail station comes from planning/airports.toml: BWI's free shuttle to the MARC/Amtrak station (timing from the airport's website, since the shuttle has no current GTFS feed) and DCA's and IAD's walkways, each with the airport's own directions. Feeds that give trips as headways (frequencies.txt: the Dulles shuttles, CUE, Annapolis Transit) are expanded into one trip per run when loaded. Nearby stops are also grouped into clusters (every pair in a cluster is less than 0.3 km apart) for the assistant's "what connects here" answers.

Fares

Each agency's fare summary is in its definition file, with the agency's fare page scraped nightly where the site allows it. VRE and MARC price trips by station, which GTFS doesn't carry, so their published charts are in planning/rail_fares.toml and trips show the exact one-way fare. Fares that vary by trip (Amtrak, FlixBus, Greyhound, Virginia Breeze, intercity buses) send riders to the operator's site.

Rider reports (crowdsourced)

Riders can warn each other from the map page (Report an issue): the station and line (if any), where the trip started and ended, the date, and what happened in their own words. Each report is saved in the transit database (rider_reports) and checked by a small Claude model (REPORTS_MODEL, default claude-haiku-5-5), which holds back off-topic or abusive posts, sorts it (delay, crowding, elevator...), writes a short neutral summary and notes the agencies, lines and stations. Published reports show on matching trip options for REPORTS_SHOW_HOURS (3) and the assistant can look them up; both always label them as unverified rider reports. Review them with transit-mcp reports list|hide|publish|delete.

Accounts: My places

Visitors (tourists especially) sign in with their email address and a 6-digit code we email them (no password), and save their hotel with check-in and check-out dates, a home, and the attractions they plan to visit, each with an optional day. Current places appear as one-tap quick picks under "Where to?", in the From and To suggestions, and as pins on the map (Go here / Start here); a hotel counts only during the stay, and past visits drop out. Accounts live in their own SQLite file (ACCOUNTS_DB), never linked to the chat log; saved places are logged as "saved" without names and are kept out of links. Codes go out by SMTP (Amazon SES on the public site; see deploy/README.md); a local server without SMTP prints the code in its log. A code works for 10 minutes and 5 tries.

Plan my trip (assistant)

The site is one panel beside the map: "Where to?" at the top, then a single conversation where trip searches appear as live cards alongside the assistant's answers. The assistant can put a trip on the map itself (show_trip, for "take me to the Zoo"), and each question carries the trip on screen, so "how do I pay for this trip?" means the option the rider picked. On phones the panel is a sheet over the map.

Signed-in visitors can plan a trip by chatting: "Plan my visit" starts planning mode. It saves their hotel and places, puts stops on days with "be there by" or "leave at" times, and works out the buses and trains between them for each day (timetable trips that arrive with time to spare, or a walk when it's close). Questions about places to eat or visit are answered with Google Places Text Search (rating, price, opening hours), never from the model's memory, capped by GOOGLE_PLACES_SEARCH_MONTHLY_BUDGET. Anyone can ask questions; saving and planning need an account. The plan is stored in the account, shown under My places, and the planning tools run only in the web app, not on the MCP server, so /mcp holds no personal data. Tool inputs are left out of the chat log.

Command line

All commands run from the project folder (.venv\Scripts\transit-mcp.exe …, or just transit-mcp … with the virtual environment activated).

transit-mcp launch                         # what start.bat runs
transit-mcp doctor                         # what check-setup.bat runs
transit-mcp ingest all                     # what refresh-data.bat runs
transit-mcp ingest gtfs --only dash,vre    # one scope (api|gtfs|web), some agencies
transit-mcp agencies                       # every system with role + fare headline
transit-mcp agencies --config              # agency files, their sources, problems
transit-mcp status                         # row counts + freshness (JSON)
transit-mcp search "how do I pay with my phone"
transit-mcp chat --open                    # web chat only
transit-mcp serve                          # MCP server over stdio
transit-mcp planner request "Reston" "Pentagon"   # the JSON an engine receives
transit-mcp planner test "Reston" "Pentagon" --engine process --command "node engines/example-js/engine.js"
transit-mcp planner schema                 # write docs/planner-schema/*.json

Re-running ingest is safe and cheap: unchanged pages and feeds are detected by content hash. One failing source never stops the rest of a run.

Agencies loaded

slug	agency	mode	data
wmata	Metrorail (WMATA)	rail	GTFS via Transitland + WMATA API (stations, incidents, fares) + wmata.com (fares, alerts, guides)
metrobus	Metrobus (WMATA)	bus	GTFS via Transitland (+ WMATA bus incidents)
vre	Virginia Railway Express	commuter rail	GTFS via Transitland
fairfax-connector	Fairfax Connector	bus	GTFS via Transitland + GTFS-realtime alerts + fare page
art	Arlington Transit	bus	GTFS via Transitland + fare and alert pages
dash	DASH (Alexandria) — fare-free	bus	GTFS via Transitland + rider page
cue	CUE (City of Fairfax)	bus	GTFS via Transitland
loudoun	Loudoun County Transit	bus	GTFS via Transitland + fare and news pages
omniride	OmniRide (PRTC)	bus	GTFS via Transitland + fare and service-update pages
virginia-breeze	Virginia Breeze	intercity coach	GTFS via Transitland + booking page
mta-md-bus	MTA Maryland Local Bus	bus	GTFS via Transitland
mta-md-commuter-bus	MTA Maryland Commuter Bus	commuter bus	GTFS via Transitland
mta-md-metro	MTA Maryland Metro SubwayLink	rail	GTFS via Transitland
mta-md-light-rail	MTA Maryland Light RailLink	rail	GTFS via Transitland
marc	MARC Train	commuter rail	GTFS via Transitland
annapolis-transit	Annapolis Transit	bus	GTFS via Transitland
harbor-connector	Harbor Connector (Baltimore)	ferry	GTFS via Transitland
potomac-valley	Potomac Valley Transit Authority	bus	GTFS via Transitland
dulles-shuttles	Dulles Airport Shuttles (garages, economy lots)	bus	GTFS via Transitland
charm-city-circulator	Charm City Circulator (Baltimore, free)	bus	GTFS via Transitland
intercity-bus	Intercity buses (combined feed)	intercity bus	GTFS via Transitland
flixbus	FlixBus	intercity bus	GTFS via Transitland
amtrak	Amtrak	intercity rail	GTFS via Transitland

The Maryland and intercity agencies have no hand-written fare or rider pages yet: the assistant points riders to each agency's own fare page from its GTFS feed.

To add one, copy agencies/_template.toml — see agencies/README.md.

Publishing the MCP server

The MCP server at https://dmvtransit.com/mcp is open: anyone can connect without a key (MCP_OPEN), at 120 requests a minute and 3,000 a day per network address (ChatGPT and Claude call from shared servers) (MCP_OPEN_RATE_PER_MINUTE, MCP_OPEN_RATE_PER_DAY) and 8,000 a day for all keyless callers (MCP_OPEN_DAILY_CAP). Keys from transit-mcp mcp-keys add get higher limits. Address lookups there use their own Google allowance (MCP_GOOGLE_GEOCODING_MONTHLY_BUDGET), so outside use never spends the website's. Every tool has a title and read-only annotations. The pages the directories ask for are /mcp-server (documentation), /privacy and /terms.

server.json describes the server for the official MCP Registry as com.dmvtransit/transit (published 1.0.0 on 2026-11-03). To publish a new version, raise version and run python tools/registry_publish.py (add --dry-run to test the sign-in only). It signs in with HTTP domain verification: the public key is served at /.well-known/mcp-registry-auth, and the private key stays outside the repo in ~/.dmvtransit/mcp-registry-key.pem; keep it safe. Published versions can't be deleted.

MCP tools

Tool	Purpose
search_transit_info(query, category?, limit?)	Search the agencies' fare / how-to / alert pages (never routes or schedules)
get_service_alerts(line?, station?, mode?, agency?)	Live disruptions: WMATA incidents + agencies' GTFS-realtime alerts
get_elevator_escalator_status(station?)	Elevator / escalator outages
get_station_info(station)	Lines, address, parking, entrances
get_fare(origin, destination, rider_type?)	Metrorail station-to-station fare
get_metro_route(origin, destination)	Metrorail lines, changes of train, direction, first/last trains, disruptions
list_topics() / get_guide(topic)	Content overview / full rider guides
list_agencies()	Every system: role, strengths, service area, fare headline
find_stops_near(place, radius_m?, agency?)	Stops/stations near a place, across agencies
get_route(agency, query)	A route's days, hours, frequency, endpoints, fare
transfers_at(place, day?, time?)	Other systems within walking distance + whether the connection works then
how_to_pay(agency)	Payment methods, where to buy, app, SmarTrip/contactless, transfers
geocode_address(query, limit?)	Where an address, hotel or landmark is: the step before planning a trip, so the LLM can confirm the place
plan_trip(origin, destination, depart_at?)	Real trip options for the 3 hours after a time (default now), with walking, waits and live times when leaving now; takes addresses, places, stations or "lat,lon"
plan_connection(origin, destination, when?)	Systems per leg, transfer hub, days it works, fares — via the configured engine; takes addresses too
get_rider_reports(station?, line?, days?)	Recent unverified reports from riders on the site (delays, crowding, elevators, tips)
estimate_trip_cost(origin, destination, when?, rider_category?)	Per-leg fares and total

Resources: transit://region/agencies, transit://wmata/freshness, transit://wmata/guide/{topic}.

Using the MCP server from another client

Over the web, for an LLM or app on another machine: https://dmvtransit.com/mcp (MCP Streamable HTTP) with an API key sent as Authorization: Bearer <key>. Keys and limits are in deploy/README.md. To run it yourself: transit-mcp mcp-keys add "who it's for", then transit-mcp serve --http (serves http://127.0.0.1:8766/mcp).

On the same machine, over stdio — Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "dmv-transit": {
      "command": "C:\\path\\to\\transit_mcp\\.venv\\Scripts\\transit-mcp.exe",
      "args": ["serve"],
      "env": { "TRANSIT_MCP_DB": "C:\\path\\to\\transit_mcp\\transit.db" }
    }
  }
}

Development

.venv\Scripts\python.exe -m pip install -e ".[dev]"

.venv\Scripts\python.exe -m pytest

Tests run offline against fixtures in tests/fixtures/ (the Node engine test runs if node is installed). Settings are documented in .env.example.

Legal

See NOTICE.md. WMATA API data is used under its Developer License Agreement; GTFS feeds are published by each agency (located through Transitland); scraping is limited to public, robots-allowed pages, rate-limited, and stored with attribution. Not affiliated with WMATA or any agency listed.