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

A Model Context Protocol (MCP) server that promises to tell you _exactly_ when the next Caltrain will arrive... and then be 10 minutes late anyway. Uses real GTFS data, so at least the disappointment is official!

Features (Or: "Why We Built This Thing")

- 🚆 "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 is too many to memorize 🤷‍♀️
- 🕐 Time-specific queries - Plan your commute with surgical precision, then watch it all fall apart
- ✨ Smart search - Type 'sf' instead of the full name because we're all lazy here
- 📊 GTFS-based - We use the same data Caltrain does, so when things go wrong, we can blame them together

Setup (The Fun Part 🙄)

1. Install dependencies (aka "More stuff to break"):

   # Install uv if you haven't already (because pip is apparently too mainstream now)
   curl -LsSf https://astral.sh/uv/install.sh | sh
# Install dependencies using uv (fingers crossed it actually works)

   uv sync

   

2. Get that sweet, sweet GTFS data:
The server expects Caltrain GTFS data in the src/caltrain_mcp/data/caltrain-ca-us/ directory. Because apparently we can't just ask the trains nicely where they are.

   uv run python scripts/fetch_gtfs.py
   

This magical script downloads files that contain:

- 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 (Good Luck!)

As an MCP Server (The Real Deal)

This server is designed to be used with MCP clients like Claude Desktop, not run directly by humans (because that would be too easy). Here's how to actually use it:

With Claude Desktop

Add this 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 and you'll have access to Caltrain schedules directly in your conversations!

With Other MCP Clients

Any MCP-compatible client can use this server by starting it with:

uvx caltrain-mcp

The server communicates via stdin/stdout using the MCP protocol. It doesn't do anything exciting when run directly - it just sits there waiting for proper MCP messages.

Testing the Server (For Development)

You can test if this thing actually works by importing it directly:

```python
from caltrain_mcp.server import next_trains, list_stations