DMV Transit

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.

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

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

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) can make an account with a username and password (no email needed) 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. Passwords are salted scrypt hashes; a recovery code shown once at sign-up resets a forgotten password, and five wrong tries lock an account for 15 minutes. Sign-in by emailed code is also built in, switched on with ACCOUNTS_EMAIL_CODES=true once SMTP works (Amazon SES on the public site; see deploy/README.md); a local server without SMTP prints the code in its log.

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 runstransit-mcp doctor                         # what check-setup.bat runstransit-mcp ingest all                     # what refresh-data.bat runstransit-mcp ingest gtfs --only dash,vre    # one scope (api|gtfs|web), some agenciestransit-mcp agencies                       # every system with role + fare headlinetransit-mcp agencies --config              # agency files, their sources, problemstransit-mcp status                         # row counts + freshness (JSON)transit-mcp search "how do I pay with my phone"transit-mcp chat --open                    # web chat onlytransit-mcp serve                          # MCP server over stdiotransit-mcp planner request "Reston" "Pentagon"   # the JSON an engine receivestransit-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

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

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.