MBTA MCP
Model Context Protocol (MCP) server that exposes live MBTA V3 transit data over Streamable HTTP.
Public production endpoint (after Cloud Run deploy):
https://mbta.metaverseprofessional.tech/mcp
Architecture
MCP Client
→ Streamable HTTP (/mcp)
→ Python MCP server (MCP Python SDK v2)
→ MBTA V3 API (https://api-v3.mbta.com)
Tools
| Tool | When to use |
|---|---|
get_routes |
List routes; optional route_type filter (0–4) |
get_stops_for_route |
Stops for a known route_id (e.g. Red, Green-B, 1) |
find_stop |
Resolve a station/stop name to stop IDs (client-side name match) |
get_next_arrivals |
Predicted arrivals at a stop_id |
get_alerts |
Service alerts; optional route/stop filters |
get_vehicles |
Live vehicle positions; optional route_id |
Also exposes GET /health for load balancers and Cloud Run probes.
Requirements
- Python 3.12+
- MBTA API key from api-v3.mbta.com
Quick start (local)
cd MBTA-MCP
py -3.12 -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
pip install -e ".[dev]"
copy .env.example .env
# Edit .env and set MBTA_API_KEY=...
python -m mbta_mcp
Server listens on:
- MCP:
http://127.0.0.1:8080/mcp - Health:
http://127.0.0.1:8080/health
Or with uvicorn:
uvicorn mbta_mcp.server:create_app --factory --host 0.0.0.0 --port 8080
Configuration
All secrets come from the environment (never hardcode keys).
| Variable | Required | Default | Description |
|---|---|---|---|
MBTA_API_KEY |
recommended | — | MBTA V3 API key (optional for light anonymous testing) |
HOST |
no | 0.0.0.0 |
Bind address |
PORT |
no | 8080 |
Bind port (Cloud Run sets this) |
MBTA_BASE_URL |
no | https://api-v3.mbta.com |
API base URL |
LOG_LEVEL |
no | INFO |
Logging level |
MCP_ALLOWED_HOSTS |
no | localhost + production host | Streamable HTTP Host allowlist |
See .env.example.
Tests
pytest
pytest -m integration # live MBTA calls when MBTA_API_KEY is set
Smoke-test tools against a running server:
python scripts/smoke_tools.py --url http://127.0.0.1:8080/mcp
Docker
docker build -t mbta-mcp .
docker run --rm -p 8080:8080 -e MBTA_API_KEY=your_key mbta-mcp
Then:
curl http://127.0.0.1:8080/health
python scripts/smoke_tools.py --url http://127.0.0.1:8080/mcp
Connect an MCP client
Point a Streamable HTTP MCP client at:
- Local:
http://127.0.0.1:8080/mcp - Production:
https://mbta.metaverseprofessional.tech/mcp
Cloud Run (later — do not deploy until local + Docker work)
- Store the key in Secret Manager as
MBTA_API_KEY. - Build/push the image to Artifact Registry.
- Deploy to Cloud Run with:
- secret mapped to env var
MBTA_API_KEY - container port
8080 - health check path
/health
- secret mapped to env var
- Map custom domain
mbta.metaverseprofessional.tech. - Ensure
MCP_ALLOWED_HOSTSincludesmbta.metaverseprofessional.techandmbta.metaverseprofessional.tech:*.
App code only reads MBTA_API_KEY from the environment; Secret Manager wiring is a Cloud Run concern.
Project layout
src/mbta_mcp/
server.py # MCPServer, tools, /health
config.py # env settings
mbta/client.py # MBTA V3 httpx client
tools/ # tool handlers
tests/
Dockerfile
License
Use at your own risk. MBTA data is subject to MBTA API terms of use.
