MBTA MCP Server

An MCP (Model Context Protocol) server for the MBTA V3 API, providing access to Boston's public transit data.

Features

• Routes: Get information about MBTA routes (subway, bus, commuter rail, ferry)
• Stops: Find transit stops by location, route, or ID
• Predictions: Real-time arrival predictions
• Schedules: Scheduled service times
• Trips: Trip information and details
• Alerts: Service alerts and disruptions
• Vehicles: Real-time vehicle positions
• Trip Planning: Intelligent multi-modal journey planning with real-time data
• Route Alternatives: Alternative routing options with transfer optimization
• External APIs: Vehicle positions and alerts from external sources
• Track Predictions: Machine learning-powered track assignment predictions
• Historical Data: Access to historical track assignments and performance metrics
• Caching: Memory-based caching with configurable TTL for improved performance

Installation

Option 1: Direct run with uv (Easiest)

No installation required! Just run directly:

uv tool run mbta-mcp

Set your MBTA API key as an environment variable:

export MBTA_API_KEY=your_api_key_here
uv tool run mbta-mcp

Option 2: Install as a tool

Install directly with uv tool:

uv tool install mbta-mcp

Set your MBTA API key:

export MBTA_API_KEY=your_api_key_here

Run the server:

mbta-mcp

Option 3: Development Setup

1. Clone and install dependencies:

   git clone https://github.com/cubismod/mbta-mcp.git
   cd mbta-mcp
   uv sync

1. Configure your MBTA API key:

   cp .env.example .env
   # Edit .env and add your MBTA_API_KEY

1. Get an API key from <https://api-v3.mbta.com>

Usage

MCP Server (for AI clients)

Run the MCP server for use with AI clients like Claude Desktop:

# Direct run (no installation needed)
uv tool run mbta-mcp

# If installed as a tool
mbta-mcp

# If using development setup
uv run mbta-mcp

CLI Interface (for direct usage)

For direct command-line access to MBTA and Amtrak data:

# Show available commands
uv run mbta-cli --help

# Get Amtrak trains
uv run mbta-cli trains --limit 5

# Get Amtrak trains in JSON format
uv run mbta-cli trains --json --limit 3

# Test MBTA routes
uv run mbta-cli routes

# Show available MCP tools
uv run mbta-cli tools

Available Tools

Core Transit Data:

• mbta_get_routes - Get MBTA routes (subway, bus, commuter rail, ferry)
• mbta_get_stops - Get MBTA stops by ID, route, or location
• mbta_get_predictions - Get real-time arrival predictions
• mbta_get_schedules - Get scheduled service times
• mbta_get_trips - Get trip information and details
• mbta_get_alerts - Get service alerts and disruptions
• mbta_get_vehicles - Get real-time vehicle positions

Trip Planning:

• mbta_plan_trip - Plan multi-modal journeys with real-time data and transfer optimization
• mbta_get_route_alternatives - Find alternative routes with different transit modes

Extended Features:

• mbta_get_services - Get service definitions and calendars
• mbta_get_shapes - Get route shape/path information for mapping
• mbta_get_facilities - Get facility information (elevators, escalators, parking)
• mbta_get_live_facilities - Get real-time facility status and outages
• mbta_search_stops - Search for stops by name or near a location
• mbta_get_nearby_stops - Get stops near a specific location
• mbta_get_predictions_for_stop - Get all predictions for a specific stop

External API Tools:

• mbta_get_vehicle_positions - Get real-time vehicle positions from external API (GeoJSON format)
• mbta_get_external_alerts - Get general alerts from external API (delays, disruptions, service info)

Boston Amtrak Tracker API:

• mbta_get_amtrak_trains - Get all tracked Amtrak trains from Boston Amtrak Tracker API
• mbta_get_amtrak_trains_geojson - Get Amtrak trains as GeoJSON for mapping applications
• mbta_get_amtrak_health_status - Get health status of the Boston Amtrak Tracker API

IMT Track Prediction API:

• mbta_get_track_prediction - Predict which track a train will use at a station
• mbta_get_chained_track_predictions - Get multiple track predictions in a single request
• mbta_get_prediction_stats - Get prediction statistics and accuracy metrics
• mbta_get_historical_assignments - Get historical track assignments for analysis

Tool Reference

Core Transit Data Tools

#### mbta_get_routes

Get information about MBTA routes including subway, bus, commuter rail, and ferry services.

• Parameters: route_id (optional), route_type (optional), page_limit (default: 10)
• Route Types: 0=Light Rail, 1=Subway, 2=Commuter Rail, 3=Bus, 4=Ferry

#### mbta_get_stops

Find transit stops by location, route, or ID with optional filtering.

• Parameters: stop_id (optional), route_id (optional), latitude/longitude (optional), radius (optional), page_limit (default: 10)

#### mbta_get_predictions

Get real-time arrival predictions for MBTA services.

• Parameters: stop_id (optional), route_id (optional), trip_id (optional), page_limit (default: 10)

#### mbta_get_schedules

Get scheduled service times and departure information.

• Parameters: stop_id (optional), route_id (optional), trip_id (optional), direction_id (optional), page_limit (default: 10)

#### mbta_get_trips

Get trip information and details for MBTA services.

• Parameters: trip_id (optional), route_id (optional), direction_id (optional), page_limit (default: 10)

#### mbta_get_alerts

Get service alerts and disruptions affecting MBTA services.

• Parameters: alert_id (optional), route_id (optional), stop_id (optional), page_limit (default: 10)

#### mbta_get_vehicles

Get real-time vehicle positions and status information.

• Parameters: vehicle_id (optional), route_id (optional), trip_id (optional), page_limit (default: 10)

Extended Features Tools

#### mbta_get_services

Get service definitions and calendars for MBTA operations.

• Parameters: service_id (optional), page_limit (default: 10)

#### mbta_get_shapes

Get route shape/path information for mapping and visualization.

• Parameters: shape_id (optional), route_id (optional), page_limit (default: 10)

#### mbta_get_facilities

Get facility information including elevators, escalators, and parking areas.

• Parameters: facility_id (optional), stop_id (optional), facility_type (optional), page_limit (default: 10)

#### mbta_get_live_facilities

Get real-time facility status and outage information.

• Parameters: facility_id (optional), page_limit (default: 10)

#### mbta_search_stops

Search for stops by name or near a specific location.

• Parameters: query (required), latitude/longitude (optional), radius (optional), page_limit (default: 10)

#### mbta_get_nearby_stops

Get stops near a specific location within a specified radius.

• Parameters: latitude (required), longitude (required), radius (default: 1000), page_limit (default: 10)

#### mbta_get_predictions_for_stop

Get all predictions for a specific stop with optional filtering.

• Parameters: stop_id (required), route_id (optional), direction_id (optional), page_limit (default: 10)

External API Tools

#### mbta_get_vehicle_positions

Get real-time vehicle positions from external API in GeoJSON format.

• Parameters: None
• Returns: GeoJSON with vehicle locations, routes, status, speed, and bearing information

#### mbta_get_external_alerts

Get general alerts from external API including delays, disruptions, and service information.

• Parameters: None
• Returns: JSON with alert details, severity levels, affected routes/stops, and active periods

Boston Amtrak Tracker API Tools

#### mbta_get_amtrak_trains

Get all tracked Amtrak trains from the Boston Amtrak Tracker API.

• Parameters: None
• Returns: JSON with real-time Amtrak train locations, routes, status, speed, and other information

#### mbta_get_amtrak_trains_geojson

Get Amtrak trains as GeoJSON for mapping applications.

• Parameters: None
• Returns: GeoJSON feature collection with train locations suitable for mapping

#### mbta_get_amtrak_health_status

Get health status of the Boston Amtrak Tracker API.

• Parameters: None
• Returns: JSON with server health status and last data update time

IMT Track Prediction API Tools

#### mbta_get_track_prediction

Predict which track a train will use at a specific station using machine learning.

• Parameters: station_id (required), route_id (required), trip_id (required), headsign (required), direction_id (required), scheduled_time (required)
• Returns: Track prediction with confidence score and prediction method

#### mbta_get_chained_track_predictions

Get multiple track predictions in a single request for batch processing.

• Parameters: predictions (required) - Array of prediction request objects
• Returns: Array of track predictions with confidence scores

#### mbta_get_prediction_stats

Get prediction statistics and accuracy metrics for a station and route.

• Parameters: station_id (required), route_id (required)
• Returns: Statistics including accuracy rate, total predictions, correct predictions, and average confidence

#### mbta_get_historical_assignments

Get historical track assignments for analysis and pattern recognition.

• Parameters: station_id (required), route_id (required), days (default: 30)
• Returns: Historical track assignment data with actual usage patterns

Trip Planning Tools

The MBTA MCP server provides intelligent trip planning capabilities that combine real-time transit data with multi-modal journey optimization. These tools help plan efficient journeys across the MBTA network with support for accessibility requirements and transfer preferences.

#### mbta_plan_trip

Plan multi-modal journeys with real-time data and transfer optimization. This tool finds the best transit routes between two locations, considering walking distance, transfer limits, and accessibility requirements.

Parameters:

• origin_lat (required): Origin latitude coordinate
• origin_lon (required): Origin longitude coordinate
• dest_lat (required): Destination latitude coordinate
• dest_lon (required): Destination longitude coordinate
• departure_time (optional): ISO 8601 formatted departure time (e.g., "2025-01-01T10:00:00-05:00")
• max_walk_distance (optional): Maximum walking distance in meters (default: 800)
• max_transfers (optional): Maximum number of transfers allowed (default: 2)
• prefer_fewer_transfers (optional): Prioritize routes with fewer transfers (default: true)
• wheelchair_accessible (optional): Only include accessible routes and vehicles (default: false)

Returns: JSON with trip options including:

• Origin and destination coordinates with nearby transit stops
• Multiple route alternatives with detailed segments
• Walking directions and transit connections
• Real-time departure predictions and schedule information
• Transfer points and walking times between stations
• Accessibility information for each route option

Example Usage:

Plan a trip from MIT to Harvard Square:
- origin_lat: 42.3601
- origin_lon: -71.0942  
- dest_lat: 42.3736
- dest_lon: -71.1190
- max_walk_distance: 600
- prefer_fewer_transfers: true

#### mbta_get_route_alternatives

Find alternative routes with different transit modes. This tool excludes specified primary route types to discover backup options, useful when primary routes have service disruptions.

Parameters:

• origin_lat (required): Origin latitude coordinate
• origin_lon (required): Origin longitude coordinate
• dest_lat (required): Destination latitude coordinate
• dest_lon (required): Destination longitude coordinate
• primary_route_modes (optional): Array of route type IDs to exclude (e.g., ["1"] to exclude subway)
• departure_time (optional): ISO 8601 formatted departure time
• max_walk_distance (optional): Maximum walking distance in meters (default: 800)
• max_transfers (optional): Maximum transfers (default: 2)
• wheelchair_accessible (optional): Require accessible routes (default: false)

Route Type IDs:

• "0" - Light Rail (Green Line branches)
• "1" - Subway (Red, Orange, Blue Lines)
• "2" - Commuter Rail
• "3" - Bus
• "4" - Ferry

Returns: Alternative route options excluding the specified primary modes, with the same detailed structure as mbta_plan_trip.

Example Usage:

Find bus alternatives when subway is disrupted:
- origin_lat: 42.3601
- origin_lon: -71.0942
- dest_lat: 42.3736  
- dest_lon: -71.1190
- primary_route_modes: ["1", "0"]  // Exclude subway and light rail
- max_walk_distance: 1000

Trip Planning Use Cases

Morning Commute Planning: Use mbta_plan_trip with departure time to find the best route for your daily commute, considering real-time delays and service alerts.

Accessibility-First Routing: Enable wheelchair_accessible: true to ensure all suggested routes are fully accessible, including elevators and ramps at stations.

Service Disruption Backup: When alerts indicate subway delays, use mbta_get_route_alternatives to find bus routes that avoid the affected lines.

Event Planning: For large events, plan trips with longer walking distances and more transfers to distribute passenger load across the transit network.

Tourist Assistance: Combine trip planning with nearby stops and predictions to help visitors navigate Boston's transit system efficiently.

Integration with LLMs

Claude Desktop

#### Option 1: Using uv tool run (Easiest - No Installation Required)

Add to Claude Desktop configuration:

On macOS, edit ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "mbta": {
      "command": "uv",
      "args": ["tool", "run", "mbta-mcp"],
      "env": {
        "MBTA_API_KEY": "your_api_key_here"
      }
    }
  }
}

On Windows, edit %APPDATA%\Claude\claude_desktop_config.json with the same content.

#### Option 2: Using uv tool install (Recommended for Regular Use)

1. Install the MCP server:

   uv tool install mbta-mcp

1. Add to Claude Desktop configuration:

On macOS, edit ~/Library/Application Support/Claude/claude_desktop_config.json:

   {
     "mcpServers": {
       "mbta": {
         "command": "mbta-mcp",
         "env": {
           "MBTA_API_KEY": "your_api_key_here"
         }
       }
     }
   }

On Windows, edit %APPDATA%\Claude\claude_desktop_config.json with the same content.

#### Option 3: Using development setup

1. Clone and setup the MCP server:

   git clone https://github.com/cubismod/mbta-mcp.git
   cd mbta-mcp
   task install-dev
   task verify  # Ensure everything works

1. Configure your MBTA API key:

   cp .env.example .env
   # Edit .env and add: MBTA_API_KEY=your_api_key_here

1. Add to Claude Desktop configuration:

On macOS, edit ~/Library/Application Support/Claude/claude_desktop_config.json:

   {
     "mcpServers": {
       "mbta": {
         "command": "uv",
         "args": ["run", "mbta-mcp"],
         "cwd": "/path/to/your/mbta-mcp",
         "env": {
           "MBTA_API_KEY": "your_api_key_here"
         }
       }
     }
   }

On Windows, edit %APPDATA%\Claude\claude_desktop_config.json with the same content.

Restart Claude Desktop and you'll see "mbta" in the 🔌 icon, indicating the MCP server is connected.

Other MCP-Compatible LLMs

#### Continue.dev

Using uv tool run (easiest):

{
  "mcpServers": [
    {
      "name": "mbta",
      "command": "uv",
      "args": ["tool", "run", "mbta-mcp"],
      "env": {
        "MBTA_API_KEY": "your_api_key_here"
      }
    }
  ]
}

Using uv tool installation:

{
  "mcpServers": [
    {
      "name": "mbta",
      "command": "mbta-mcp",
      "env": {
        "MBTA_API_KEY": "your_api_key_here"
      }
    }
  ]
}

Or with development setup:

{
  "mcpServers": [
    {
      "name": "mbta",
      "command": "uv",
      "args": ["run", "mbta-mcp"],
      "cwd": "/path/to/your/mbta-mcp",
      "env": {
        "MBTA_API_KEY": "your_api_key_here"
      }
    }
  ]
}

#### Codeium

Using uv tool run (easiest):

{
  "mcp": {
    "servers": {
      "mbta": {
        "command": ["uv", "tool", "run", "mbta-mcp"],
        "env": {
          "MBTA_API_KEY": "your_api_key_here"
        }
      }
    }
  }
}

Using uv tool installation:

{
  "mcp": {
    "servers": {
      "mbta": {
        "command": ["mbta-mcp"],
        "env": {
          "MBTA_API_KEY": "your_api_key_here"
        }
      }
    }
  }
}

Or with development setup:

{
  "mcp": {
    "servers": {
      "mbta": {
        "command": ["uv", "run", "mbta-mcp"],
        "cwd": "/path/to/your/mbta-mcp",
        "env": {
          "MBTA_API_KEY": "your_api_key_here"
        }
      }
    }
  }
}

#### Generic MCP Client

Using uv tool run (easiest):

• Command: uv tool run mbta-mcp
• Environment: MBTA_API_KEY=your_api_key_here

Using uv tool install:

• Command: mbta-mcp
• Environment: MBTA_API_KEY=your_api_key_here

Using development setup:

• Command: uv run mbta-mcp
• Working Directory: /path/to/your/mbta-mcp
• Environment: MBTA_API_KEY=your_api_key_here

Usage Examples

Once connected, you can ask your LLM questions like:

Core Transit Information:

• "What are the next Red Line trains from Harvard?"
• "Are there any service alerts for the Green Line?"
• "Find the nearest T stops to 42.3601° N, 71.0589° W"
• "What bus routes serve Kendall Square?"
• "Show me the schedule for Route 1 bus"
• "Get real-time vehicle positions for all MBTA vehicles"
• "What are the current service alerts and delays?"

Trip Planning:

• "Plan a trip from MIT (42.3601, -71.0942) to Harvard Square (42.3736, -71.1190)"
• "How do I get from Back Bay to Logan Airport using only accessible routes?"
• "Find alternative routes from Downtown Crossing to Fenway that avoid the Green Line"
• "Plan a wheelchair-accessible journey from South Station to Cambridge with minimal walking"
• "What's the best way to get from Kendall Square to Copley at 8:30 AM tomorrow?"
• "Show me bus alternatives from Harvard to MIT when the Red Line is down"
• "Plan a trip allowing up to 1200 meters of walking and 3 transfers maximum"

Advanced Features:

• "Predict which track the 3:30 PM Providence train will use at South Station"
• "Show me track prediction accuracy statistics for South Station"
• "Get historical track assignments for the last 30 days"
• "Get all current Amtrak trains in the Boston area"
• "Show me Amtrak trains as GeoJSON for mapping"
• "Check the health status of the Amtrak tracker API"

Troubleshooting

Server not connecting:

1. Verify the path in your config is correct
2. Ensure uv is installed and in your PATH
3. Check that the MBTA API key is valid
4. Run task test-server to verify the server works

API rate limiting:

• The MBTA API has rate limits; the server includes pagination to manage this
• Some endpoints work without an API key, but having one increases limits

Configuration issues:

• Ensure your .env file is in the project root
• API key should be set as MBTA_API_KEY=your_key_here
• Check Claude Desktop logs if the server fails to start

API Key Requirements

• Free access: Many endpoints work without an API key (with lower rate limits)
• API key benefits: Higher rate limits and access to all features
• Get a key: Register at <https://api-v3.mbta.com>
• Usage: Set in .env file or environment variable MBTA_API_KEY

External APIs

This MCP server integrates with additional external APIs to provide enhanced functionality:

Vehicle Positions API

• Endpoint: <https://vehicles.ryanwallace.cloud/>
• Format: GeoJSON with real-time vehicle locations, routes, and status
• No authentication required
• Data: Vehicle coordinates, route information, speed, bearing, occupancy status

External Alerts API

• Endpoint: <https://vehicles.ryanwallace.cloud/alerts>
• Format: JSON with service alerts, delays, and disruptions
• No authentication required
• Data: Alert headers, effects, severity levels, affected routes/stops, active periods

IMT Track Prediction API

• Endpoint: <https://imt.ryanwallace.cloud/>
• Format: JSON with machine learning-powered track predictions
• No authentication required
• Data: Track predictions, confidence scores, historical assignments, accuracy metrics

Boston Amtrak Tracker API

• Endpoint: <https://bos.ryanwallace.cloud/>
• Format: JSON and GeoJSON with real-time Amtrak train tracking
• No authentication required
• Data: Train locations, routes, status, speed, and health information

Development

This project uses Task for build automation. Install it and run:

task --list  # Show available tasks

Common Tasks

task install-dev    # Install dependencies including dev tools
task check          # Run all checks (format, lint, typecheck)
task test-server    # Test MCP server functionality
task run            # Run the MBTA MCP server
task verify         # Full project verification

Manual Commands

Install dev dependencies:

uv sync --dev

Run formatters and linters:

task format     # or: uv run ruff format mbta_mcp/
task lint       # or: uv run ruff check mbta_mcp/
task typecheck  # or: uv run mypy mbta_mcp/