Caltrain MCP

🚂 Caltrain MCP Server (Because You Love Waiting for Trains)

This Model Context Protocol (MCP) server claims to precisely inform you when the next Caltrain will arrive. However, it often ends up being 10 minutes late. It uses real GTFS data, so at least the disappointment is official!

🚀 Quick Start

This server is designed to be used with MCP clients like Claude Desktop. Follow the steps below to get started.

✨ Features

• 🚆 "Real-time" train schedules: Get the next departures between any two stations (actual arrival times may vary by +/- infinity).
• 📍 Station lookup: Because apparently 31 stations are too many to memorize.
• 🕐 Time-specific queries: Plan your commute precisely, then watch it all go wrong.
• ✨ Smart search: Type 'sf' instead of the full name because we're all lazy.
• 📊 GTFS-based: We use the same data as Caltrain, so when things go wrong, we can blame them together.

📦 Installation

1. Install dependencies:

   # Install uv if you haven't already
   curl -LsSf https://astral.sh/uv/install.sh | sh
   
   # Install dependencies using uv
   uv sync
   

2. Get GTFS data: The server expects Caltrain GTFS data in the src/caltrain_mcp/data/caltrain-ca-us/ directory.

   uv run python scripts/fetch_gtfs.py
   

   This script downloads files including:
   • stops.txt: All the places trains pretend to stop.
   • trips.txt: Theoretical journeys through space and time.
   • stop_times.txt: When trains are supposed to arrive (spoiler: they don't).
   • calendar.txt: Weekday vs weekend schedules (because trains also need work-life balance).

💻 Usage Examples

Basic Usage

As an MCP Server with Claude Desktop

Add the following to your Claude Desktop MCP configuration file:

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

This will automatically install and run the latest version from PyPI. Then restart Claude Desktop to access Caltrain schedules in conversations.

With Other MCP Clients

Start the server with:

uvx caltrain-mcp

The server communicates via stdin/stdout using the MCP protocol.

Advanced Usage

Testing the Server

from caltrain_mcp.server import next_trains, list_stations

# Test next trains functionality
result = await next_trains('San Jose Diridon', 'San Francisco')
print(result)

# Test stations list
stations = await list_stations()
print(stations)

📚 Documentation

Available Tools

next_trains(origin, destination, when_iso=None)

Ask when the next train will arrive. The server will use GTFS data to give technically accurate times.

• Parameters:
  • origin (str): Your current location.
  • destination (str): Your desired destination.
  • when_iso (str, optional): The time you want to travel.
• Examples:

# Next trains from current time
next_trains('San Jose Diridon', 'San Francisco')

# Trains at a specific time
next_trains('Palo Alto', 'sf', '2025-05-23T06:00:00')

# Using abbreviations
next_trains('diridon', 'sf')

list_stations()

Get a list of all 31 Caltrain stations.

• Returns: A formatted list of stations.

Station Name Recognition

The server supports various ways to enter station names:

• Full names: "San Jose Diridon Station"
• Short names: "San Francisco"
• Abbreviations: "sf" → "San Francisco"
• Partial matching: "diridon" matches "San Jose Diridon Station"

Available Stations

The server covers all Caltrain stations:

• San Francisco to San Jose: San Francisco, 22nd Street, Bayshore, South San Francisco, San Bruno, Millbrae, Broadway, Burlingame, San Mateo, Hayward Park, Hillsdale, Belmont, San Carlos, Redwood City, Menlo Park, Palo Alto, Stanford, California Avenue, San Antonio, Mountain View, Sunnyvale, Lawrence, Santa Clara, College Park, San Jose Diridon
• San Jose to Gilroy: Tamien, Capitol, Blossom Hill, Morgan Hill, San Martin, Gilroy

Sample Output

🚆 Next Caltrain departures from San Jose Diridon Station to San Francisco Caltrain Station on Thursday, May 22, 2025:
• Train 153: 17:58:00 → 19:16:00 (to San Francisco)
• Train 527: 18:22:00 → 19:22:00 (to San Francisco)
• Train 155: 18:28:00 → 19:46:00 (to San Francisco)
• Train 429: 18:43:00 → 19:53:00 (to San Francisco)
• Train 157: 18:58:00 → 20:16:00 (to San Francisco)

Actual arrival times may vary. Side effects may include existential dread and a deep appreciation for remote work.

🔧 Technical Details

• GTFS Processing: Automatically handle the relationship between stations and platforms.
• Service Calendar: Respect weekday/weekend schedules.
• Data Types: Handle mixed integer/string formats in GTFS files.
• Time Parsing: Support 24+ hour format for late-night services.
• Error Handling: Gracefully fail when an invalid station name is entered.

Project Structure

caltrain-mcp/
├── .github/workflows/         # GitHub Actions (the CI/CD overlords)
│   ├── ci.yml                 # Main CI pipeline (linting, testing, the works)
│   └── update-gtfs.yml        # Automated GTFS data updates
├── src/caltrain_mcp/          # Main package (because modern Python demands structure)
│   ├── data/caltrain-ca-us/   # GTFS data storage (where CSV files go to retire)
│   ├── __init__.py            # Package initialization (the ceremony of Python)
│   ├── __main__.py            # Entry point for python -m caltrain_mcp
│   ├── server.py              # MCP server implementation (where the magic happens)
│   └── gtfs.py                # GTFS data processing (aka "CSV wrestling")
├── scripts/                   # Utility scripts (the supporting cast)
│   ├── __init__.py            # Makes scripts a proper Python package
│   ├── fetch_gtfs.py          # Downloads the latest disappointment data
│   └── lint.py                # Run all CI checks locally (before embarrassment)
├── tests/                     # Test suite (because trust but verify)
│   ├── conftest.py            # Shared test fixtures (the common ground)
│   ├── test_gtfs.py           # GTFS functionality tests (8 tests of data wrangling)
│   ├── test_server.py         # Server functionality tests (4 tests of MCP protocol)
│   └── test_fetch_gtfs.py     # Data fetching tests (7 tests of download chaos)
├── .pre-commit-config.yaml    # Pre-commit hooks configuration
├── pyproject.toml             # Modern Python config (because setup.py is so 2020)
└── README.md                  # This literary masterpiece

Development & Testing

Code Quality & CI/CD

This project uses modern Python tooling:

• Ruff: Fast linting and formatting.
• MyPy: Type checking.
• Pytest: Testing framework with coverage reporting.

Release Process

• Semantic Versioning: Version numbers are determined from commit messages using Conventional Commits.
• Automatic Tagging: Version tags are created automatically when pushing to main.
• PyPI Publishing: Tagged releases are automatically built and published to PyPI via GitHub Actions.
• Trusted Publishing: Uses OIDC authentication with PyPI.

Making a Release

Commit using the conventional commit format and push to main:

# For bug fixes (patch version bump: 1.0.0 → 1.0.1)
git commit -m "fix: correct station name lookup bug"

# For new features (minor version bump: 1.0.0 → 1.1.0)
git commit -m "feat: add support for weekend schedules"

# For breaking changes (major version bump: 1.0.0 → 2.0.0)
git commit -m "feat!: redesign API structure"
# or
git commit -m "feat: major API changes

BREAKING CHANGE: This changes the function signatures"

The semantic-release workflow will:

1. Analyze commit messages.
2. Determine the version bump.
3. Create a git tag.
4. Generate a changelog.
5. Trigger the release workflow to publish to PyPI.

Local Testing

# Build packages locally
uv run python -m build --sdist --wheel

# Validate packages
uv run twine check dist/*

# Test upload to Test PyPI (optional)
uv run twine upload --repository testpypi dist/*

GitHub Actions CI

Every PR and push to main triggers automatic checks:

• ✅ Linting: Ruff checks for code quality issues.
• ✅ Formatting: Ensures consistent code style.
• ✅ Type Checking: MyPy validates type annotations.
• ✅ Tests: Full test suite with coverage reporting.
• ✅ Coverage: Test coverage reporting in CI logs.

The CI will reject your PR if any checks fail.

MCP Integration

This server implements the Model Context Protocol (MCP), working seamlessly with AI assistants and other MCP clients. Once configured:

• Claude Desktop: Ask Claude about train schedules in conversation.
• Other MCP Clients: Any MCP-compatible tool can access Caltrain data.
• Real-time Integration: AI can check schedules, suggest routes, and help plan trips.
• Natural Language: No need to remember station names or command syntax.

The server exposes two main tools:

• next_trains: Get upcoming departures between stations.
• list_stations: Browse all available Caltrain stations.

📄 License

This project uses official Caltrain GTFS data. If something goes wrong, blame them, not us. We're just the messenger.

Built with ❤️ and a concerning amount of caffeine in the Bay Area, where public transit is both a necessity and a source of eternal suffering.