bostonmove

bostonmove

[CI] [PyPI] [Python] [MCP registry] [License]

Getting around Boston from live public data: MBTA departures and service alerts, Bluebikes bike and dock counts, and door-to-door options: walk, Bluebikes, one MBTA route, or one change between subway lines. A command-line tool and an MCP server, so Claude Code, Claude Desktop, Cursor and other agents can answer "when's the next train" or "is there a dock near Kendall" with real numbers. It only reads public data.

$ bostonmove plan "Northeastern" "Harvard"Northeastern University  →  Harvard  (4424 m straight line)   27 min  Green Line E to Medford/Tufts: board at Northeastern University (0 min walk) now, ride 10, off at Park Street; then Red Line to Alewife: leaves 16:22, ride 9, off at Harvard  (arrive ~16:31)   28 min  Orange Line to Oak Grove: board at Massachusetts Avenue (6 min walk) in 6 min, ride 6, off at Downtown Crossing; then Red Line to Alewife: leaves 16:20, ride 11, off at Harvard  (arrive ~16:31)   29 min  Bluebikes from Forsyth St at Huntington Ave (13 bikes) to Church St (1 docks)  (arrive ~16:33)   40 min  1 to Harvard: board at Massachusetts Ave @ St Botolph St (7 min walk) in 15 min, ride 23, off at Massachusetts Ave opp Holyoke St  (arrive ~16:43)   69 min  walk, about 5751 m  (arrive ~17:12)  · Walking and cycling times are estimates from straight-line distance; transit times are from MBTA live predictions, or the timetable when there are none.  · MBTA options are one route, or one change between subway and light-rail lines with 3 min to change; changes involving buses aren't planned (mbta.com/trip-planner does them).

Install

uvx bostonmove plan "South Station" "Kendall"   # run once without installinguv tool install bostonmove                      # or: pipx install bostonmove / pip install bostonmove

Add it to Claude Code:

claude mcp add --scope user bostonmove -- uvx bostonmove mcp

Or in any MCP client's config (Claude Desktop, Cursor):

{ "mcpServers": { "bostonmove": { "command": "uvx", "args": ["bostonmove", "mcp"] } } }

If the client can't find uvx, use the full path that which uvx (macOS, Linux) or where uvx (Windows) prints as the command.

MBTA API key (optional, free). Without one the MBTA allows 20 requests a minute, which two or three trip plans can use up. With a key from api-v3.mbta.com it's 1,000. Set MBTA_API_KEY in the environment, or pass it in the MCP config with "env": {"MBTA_API_KEY": "..."}. When the limit is hit, bostonmove says so; plan_trip still returns the walking and Bluebikes options.

Tools

A place can be a station name (Park Street, Kendall, Northeastern), an MBTA stop id (place-pktrm, 110), a Bluebikes station name, an address or landmark (Fenway Park, 360 Huntington Ave), or lat,lon. Every result carries sources and as_of. Add --json to any CLI command for the full result.

How the numbers are made

• Departures are the MBTA's live predictions. When a stop has none (late at night, or a route that doesn't publish them), the timetable is used and each time is marked scheduled.
• Transit trip times: wait from the live prediction, ride time from that trip's own predicted times at the two stops (or its timetable), walking at each end estimated. A departure you can't walk to in time is skipped.
• Changes: when no subway or light-rail line goes the whole way, bostonmove looks for a line near the start and a line near the destination that share a station (Park Street, Downtown Crossing, State, Haymarket...), ranks the pairs by walking plus stops travelled, and prices the best two with live departures. The second train must leave at least 3 minutes after the first gets in.
• Walking and cycling are estimates: straight-line distance × 1.3 for streets, at 5 km/h walking and 14 km/h on a bike. They are labelled estimate.
• Bike counts are as of the Bluebikes feed time (it refreshes about once a minute); a bike or dock can be taken before you get there. In this feed the bike count includes e-bikes, so classic = bikes - ebikes.
• Alerts on a trip are only the ones that matter for that ride: severity 5 or more on its routes, or any alert at a stop where it boards, changes or gets off.

Limits

• At most one change, and only between subway and light-rail lines (Red, Orange, Blue, the Green Line branches, Mattapan). Bus to train, bus to bus, commuter rail and two-change trips aren't planned; use mbta.com/trip-planner for those.
• A plan costs 4 to 16 MBTA requests. On the keyless limit bostonmove waits up to 20 seconds for the count to reset rather than fail; past that it leaves the MBTA options out and says why.
• Stops and bike stations are searched within 800 m of each end of a trip.
• Names are matched to MBTA and Bluebikes stations first, then geocoded with OpenStreetMap inside greater Boston. An ambiguous name can land on the wrong place; the result always says what it resolved to.

Data and credit

• MBTA data from the MBTA V3 API, under the MassDOT Developers License Agreement. bostonmove is not affiliated with or endorsed by the MBTA.
• Bluebikes data from the public GBFS feed, under the Bluebikes data license. Not affiliated with Bluebikes or Lyft.
• Place search by OpenStreetMap Nominatim, data © OpenStreetMap contributors (ODbL). Lookups follow its usage policy: at most one a second, an identifying User-Agent, and results cached for 30 days.

Slow-changing data (station lists, a route's stop order, geocoded places) is cached on disk for a day in ~/.cache/bostonmove (BOSTONMOVE_CACHE_DIR to move it, BOSTONMOVE_NO_CACHE=1 to turn it off). Live data is cached in memory for under a minute.

Development

uv syncuv run pytest            # offline: replays recorded real responses with the clock frozenuv run pytest -m live    # against the real APIsuv run python tests/record_fixtures.py   # re-record the fixtures

MIT licence.