transit-mcp 🚊

Multi-city US Public Transit Model Context Protocol (MCP) server & interactive CLI supporting 13 major metro systems and county networks: Minneapolis-St. Paul (Metro Transit), Boston (MBTA), SF Bay Area (BART), San Francisco (Muni), East Bay (AC Transit), Chicago (CTA), Portland (TriMet), Washington D.C. (WMATA), Montgomery County (Ride On), Fairfax County (Connector), Atlanta (MARTA), Miami (Miami-Dade Transit), and Nashville (WeGo).

Connect any AI assistant (Claude Desktop, Cursor, Antigravity, Claude Code, Windsurf) to live public transit schedules, real-time vehicle countdowns, platform assignments, route stops, and active service disruption alerts.

🌟 Supported Cities & Transit Agencies

🚌 Bus Coverage & Known Regional Agency Gaps

Every supported municipal transit agency provides 100% comprehensive bus route coverage across all active lines. When working across metropolitan areas, note the following agency divisions:

• San Francisco Bay Area:

  • BART (sf_bart): Regional rapid rail spine connecting San Francisco, East Bay, San Mateo, and San Jose.

  • SF Muni (sf_muni): Complete San Francisco municipal bus, trolleybus, Muni Metro light rail, historic streetcar, and cable car network.

  • AC Transit (ac_transit): Complete East Bay municipal bus network, Tempo 1T BRT corridor, Transbay express network into Salesforce Transit Center, and All-Nighter service.

  • Known External Gaps: Regional suburban carriers SamTrans (San Mateo) and VTA (Santa Clara / Silicon Valley) remain independent county agencies.

• Washington D.C. Capital Region:

  • WMATA (dc): Regional Metrorail rapid transit system and interstate Metrobus routes across DC, Maryland, and Virginia.

  • Montgomery County Ride On (ride_on): Full Montgomery County (MD) feeder network, Flash BRT corridors, and Ride On extRa express lines.

  • Fairfax Connector (fairfax_connector): Full Fairfax County (VA) feeder network, I-66/I-495 Express Lanes buses, and Reston/Tysons Silver Line feeders.

  • Known External Gaps: Prince George's County TheBus (MD) and City of Alexandria DASH (VA) operate as separate municipal agencies.

• Chicago Regional Suburbs:

  • CTA (chicago): All 8 CTA "L" rapid transit lines and all 127 CTA city bus routes.

  • Known External Gaps: Suburban buses outside Chicago city limits operated by Pace Suburban Bus and commuter rail operated by Metra are independent agencies.

Related MCP server: TFL MCP Server for Poke

🚀 Quick Start

Run CLI via npx (No Install Required)

# List supported cities
npx transit-mcp cities

# View routes in Minneapolis-St. Paul
npx transit-mcp routes --city msp blue

# Get live departures for Embarcadero station in SF
npx transit-mcp departures --city sf_bart EMBR

# View active MBTA subway alerts in Boston
npx transit-mcp alerts --city boston Red

Global Installation

npm install -g transit-mcp

# Now use the friendly 'transit' command anywhere:
transit cities
transit departures --city msp 51405
transit alerts --city chicago

🤖 MCP Client Configuration

transit-mcp connects over stdio following the official Model Context Protocol.

Claude Desktop

Add transit-mcp to your claude_desktop_config.json:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "transit": {
      "command": "npx",
      "args": ["-y", "transit-mcp"]
    }
  }
}

Or with a local build:

{
  "mcpServers": {
    "transit": {
      "command": "node",
      "args": ["E:/Development/transit-mcp/dist/index.js"]
    }
  }
}

Cursor IDE

Add to .cursor/mcp.json in your project or global Cursor Settings (Cursor Settings -> Features -> MCP Servers):

{
  "mcpServers": {
    "transit": {
      "command": "npx",
      "args": ["-y", "transit-mcp"]
    }
  }
}

Claude Code

claude mcp add transit -- npx -y transit-mcp

🛠️ MCP Tools Reference

The server exposes 5 unified MCP tools available across all supported cities:

1. list_supported_cities

Returns metadata for all available cities, agencies, transit modes, and capabilities.

• Inputs: None

• Returns: Array of SupportedCityInfo

2. list_routes

Lists transit routes/lines for a supported city with optional text search filtering.

• Inputs:

  • city (string, required): City identifier or alias (e.g. 'msp', 'boston', 'sf_bart', 'chicago', 'portland')

  • query (string, optional): Filter by line name, color, or number (e.g. 'Red', 'Blue', '66')

• Returns: Array of TransitRoute with ID, short name, long name, and mode

3. get_route_stops

Retrieves stops and stations along a specific transit route.

• Inputs:

  • city (string, required): City identifier or alias

  • route_id (string, required): Route or line identifier (e.g. '901', 'Red', '12', '100')

  • direction (string or number, optional): Direction identifier (e.g. '0', '1', 'Northbound', 'Inbound')

• Returns: Array of TransitStop with IDs, names, and GPS coordinates

4. get_departures

Fetches real-time departures, live countdown minutes, platform assignments, delay information, and trip destinations.

• Inputs:

  • city (string, required): City identifier or alias

  • stop_id (string, required): Stop ID, place code, or station name (e.g. '51405' or 'MAAM' for MSP; 'place-sstat' or 'Alewife' for Boston; 'EMBR' or 'Embarcadero' for BART; '40380' or 'Clark/Lake' for CTA; '8334' or 'Pioneer Courthouse Square' for TriMet)

• Returns: Array of TransitDeparture with countdowns, status, destinations, and timestamps

5. get_service_alerts

Retrieves active service disruptions, elevator outages, maintenance notices, and delay advisories.

• Inputs:

  • city (string, required): City identifier or alias

  • route_id (string, optional): Specific route to filter alerts

• Returns: Array of TransitAlert with severity (info, warning, severe), headline, description, and affected routes

💻 CLI Commands & Examples

1. transit cities

Lists all supported cities with agency information and features:

transit cities

2. transit routes --city <city> [query]

Find routes and lines in a city:

# Search for Blue Line in Minneapolis-St. Paul
transit routes --city msp blue

# Search for Red Line in Boston MBTA
transit routes --city boston Red

# Search for CTA 'L' routes in Chicago
transit routes --city chicago

# Search for BART routes in the SF Bay Area
transit routes --city sf_bart

# Search for Metrorail lines in Washington D.C.
transit routes --city dc

# Search for MARTA rail in Atlanta
transit routes --city atl Red

# Search for Metromover loops in Miami
transit routes --city mia Mover

# Search for WeGo Star in Nashville
transit routes --city bna Star

3. transit departures --city <city> <stop>

Inspect real-time departures:

# Minneapolis Mall of America Station
transit departures --city msp 51405

# SF Embarcadero BART Station
transit departures --city sf_bart EMBR

# Boston South Station MBTA
transit departures --city boston place-sstat

# Chicago Clark/Lake CTA 'L' Station
transit departures --city chicago 40380

# Portland Pioneer Courthouse Square
transit departures --city portland 8334

# Washington D.C. Metro Center WMATA Station
transit departures --city dc A01

# Atlanta Airport MARTA Station
transit departures --city atl AIR

# Miami Government Center Metrorail/Metromover Station
transit departures --city mia GOVT

# Nashville Riverfront Commuter Rail Station
transit departures --city bna RIV

4. transit alerts --city <city> [route]

Check active service advisories:

transit alerts --city sf_bart
transit alerts --city chicago red
transit alerts --city boston Green
transit alerts --city dc RD
transit alerts --city atl

5. transit mcp

Launches the MCP server over stdio (used by LLM desktop agents).

⚙️ Environment Variables (Optional)

All supported cities function out-of-the-box using official public endpoints. For higher rate limits or specialized hardware feeds, the following environment variables can optionally be set:

🏗️ Project Architecture

transit-mcp/
├── src/
│   ├── types.ts              # Normalized transit data models & interfaces
│   ├── registry.ts           # City adapter registry & alias matcher
│   ├── server.ts             # MCP server implementation (@modelcontextprotocol/sdk)
│   ├── cli.ts                # Commander-based CLI with formatted terminal output
│   ├── index.ts              # Entrypoint & CLI / MCP dispatcher
│   └── cities/
│       ├── msp.ts            # Minneapolis-St. Paul (Metro Transit NexTrip v2)
│       ├── boston.ts         # Boston (MBTA v3 REST API)
│       ├── sf_bart.ts        # SF Bay Area (BART REST API)
│       ├── sf_muni.ts        # San Francisco (SFMTA Muni Metro, streetcars, buses)
│       ├── ac_transit.ts     # East Bay (AC Transit Tempo BRT, Transbay buses)
│       ├── chicago.ts        # Chicago (CTA open XML alerts & 'L' system)
│       ├── cta_routes.ts     # Complete Chicago CTA 127 bus routes dictionary
│       ├── portland.ts       # Portland (TriMet MAX & Streetcar)
│       ├── dc.ts             # Washington D.C. (WMATA Metrorail & Metrobus)
│       ├── ride_on.ts        # Montgomery County (Ride On Flash BRT & buses)
│       ├── fairfax_connector.ts # Fairfax County (Connector express & Metro feeders)
│       ├── atl.ts            # Atlanta (MARTA Rail & Streetcar)
│       ├── mia.ts            # Miami (Miami-Dade Metrorail & Metromover)
│       └── bna.ts            # Nashville (WeGo Star & BRT Lite)
├── test/                     # Vitest comprehensive unit & MCP test suite (100% coverage)
├── package.json
└── tsconfig.json

🧪 Development & Testing

# Clone the repository
git clone https://github.com/aminamos/transit-mcp.git
cd transit-mcp

# Install dependencies
npm install

# Run comprehensive test suite
npm test

# Build TypeScript to dist/
npm run build

📄 License

MIT © Amin