Skip to main content
Glama
CATA Bus MCP Server

CATA Bus MCP Server

🚌 CATA Bus MCP Server

A Model Context Protocol (MCP) server that provides live and static schedule data for the Centre Area Transportation Authority (CATA) bus system in State College, PA.

🌟 Features

  • Real-time vehicle positions - Track buses live on their routes

  • Trip updates - Get delay information and predicted arrivals

  • Service alerts - Stay informed about detours and disruptions

  • Static schedule data - Access routes, stops, and scheduled times

  • Fast in-memory storage - No database required, pure Python performance

Related MCP server: mcp-cta

🚀 Quick Start

Installation

# Clone the repository
git clone https://github.com/Pranav-Karra-3301/catabus-mcp.git
cd catabus-mcp

# Install dependencies
pip install -e .

Running the Server

# Run in stdio mode (for MCP clients)
python -m catabus_mcp.server

# Run in HTTP mode (for testing)
python -m catabus_mcp.server --http

The HTTP server will be available at http://localhost:7000

🛠️ Available Tools

Tool

Description

Parameters

list_routes

Get all bus routes

None

search_stops

Find stops by name/ID

query: string

next_arrivals

Get upcoming arrivals at a stop

stop_id: string, horizon_minutes?: int

vehicle_positions

Track buses on a route

route_id: string

trip_alerts

Get service alerts

route_id?: string

💻 API Examples

Using with cURL (HTTP mode)

# List all routes
curl -X POST http://localhost:7000/mcp \
  -H "Content-Type: application/json" \
  -d '{"method":"list_routes_tool","params":{}}'

# Search for stops
curl -X POST http://localhost:7000/mcp \
  -H "Content-Type: application/json" \
  -d '{"method":"search_stops_tool","params":{"query":"HUB"}}'

# Get next arrivals
curl -X POST http://localhost:7000/mcp \
  -H "Content-Type: application/json" \
  -d '{"method":"next_arrivals_tool","params":{"stop_id":"PSU_HUB","horizon_minutes":30}}'

Integration with ChatGPT

  1. Install the MCP client in ChatGPT

  2. Add this server configuration:

{
  "name": "catabus",
  "command": "python",
  "args": ["-m", "catabus_mcp.server"],
  "description": "CATA bus schedule and realtime data"
}
  1. Ask questions like:

    • "When is the next N route bus from the HUB?"

    • "Are there any service alerts for the V route?"

    • "Show me all buses currently on the W route"

Integration with Claude Desktop

Add to your Claude Desktop configuration:

{
  "mcpServers": {
    "catabus": {
      "command": "python",
      "args": ["-m", "catabus_mcp.server"]
    }
  }
}

🧪 Development

Running Tests

# Install dev dependencies
pip install -e ".[dev]"

# Run tests
pytest

# Run with coverage
pytest --cov=catabus_mcp

Code Quality

# Format code
black src/

# Lint
ruff check src/

# Type checking
mypy src/catabus_mcp/

📊 Data Sources

This server uses official CATA data feeds:

Data is cached locally and updated:

  • Static GTFS: Daily

  • Realtime feeds: Every 15 seconds

🏗️ Architecture

catabus-mcp/
├── src/catabus_mcp/
│   ├── ingest/          # Data loading and polling
│   │   ├── static_loader.py
│   │   └── realtime_poll.py
│   ├── tools/           # MCP tool implementations
│   │   ├── list_routes.py
│   │   ├── search_stops.py
│   │   ├── next_arrivals.py
│   │   ├── vehicle_positions.py
│   │   └── trip_alerts.py
│   └── server.py        # FastMCP server
└── tests/               # Test suite

⚡ Performance

  • Warm cache response time: < 100ms for all queries

  • Memory usage: ~50MB with full GTFS data loaded

  • Rate limiting: Respects CATA's 10-second minimum between requests

📝 License

MIT License - See LICENSE file

🙏 Attribution

Transit data provided by Centre Area Transportation Authority (CATA). This project is not affiliated with or endorsed by CATA.

Built by Pranav Karra.

🤝 Contributing

Contributions are welcome! Please:

  1. Fork the repository

  2. Create a feature branch

  3. Write tests for new functionality

  4. Ensure all tests pass

  5. Submit a pull request

📞 Support

🎯 Roadmap

  • Add trip planning capabilities

  • Support for accessibility features

  • Historical data analysis

  • Geospatial queries (nearest stop)

  • Multi-agency support

✅ Manual Acceptance Checklist

  • pip install -e . completes without errors

  • python -m catabus_mcp.server starts successfully

  • Static GTFS data loads on startup

  • Realtime polling begins automatically

  • list_routes_tool returns CATA routes

  • search_stops_tool finds stops by query

  • next_arrivals_tool returns predictions with delays

  • vehicle_positions_tool shows bus locations

  • trip_alerts_tool displays active alerts

  • Tests pass with pytest

  • Type checking passes with mypy


Version: 0.1.0
Status: Production Ready
Last Updated: 2024

Available Tools

7 tools
health_checkB

Ultra-fast health check optimized for cloud pre-flight validation.

Inputs: no named parameters. Returns: object

initialize_dataB

Manually trigger GTFS data initialization.

Inputs: no named parameters. Returns: object

list_routes_toolA

List all available bus routes.

Returns a list of routes with their ID, short name, long name, and color.

Inputs: no named parameters. Returns: result

next_arrivals_toolA

Get next arrivals at a specific stop.

Args: stop_id: The stop ID to query horizon_minutes: How many minutes ahead to look (default 30)

Returns: List of upcoming arrivals with trip ID, route ID, arrival time, and delay

Inputs: stop_id (required), horizon_minutes. Returns: result

search_stops_toolB

Search for stops by name or ID.

Args: query: Search query string to match against stop names, IDs, or descriptions

Returns: List of matching stops with their ID, name, latitude, and longitude

Inputs: query (required). Returns: result

trip_alerts_toolB

Get current service alerts.

Args: route_id: Optional route ID to filter alerts (if None, returns all)

Returns: List of alerts with route ID, header, description, and severity

Inputs: route_id. Returns: result

vehicle_positions_toolA

Get current positions of vehicles on a specific route.

Args: route_id: The route ID to filter by (e.g., "BL" for Blue Loop)

Returns: List of vehicle positions with ID, coordinates, bearing, and speed

Inputs: route_id (required). Returns: result

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.6/5.0

    Scored across 7 tools

    Disambiguation5/5

    Each tool has a clearly distinct purpose targeting different aspects of bus system data: health checks, data initialization, route listing, arrival queries, stop searches, alert retrieval, and vehicle tracking. There is no overlap in functionality that would cause agent confusion.

    Naming Consistency4/5

    Most tools follow a consistent verb_noun pattern (e.g., list_routes_tool, search_stops_tool, trip_alerts_tool), but 'health_check' and 'initialize_data' deviate by lacking the '_tool' suffix. The naming is still readable and mostly predictable.

    Tool Count5/5

    With 7 tools, this server is well-scoped for a bus transit system, covering essential operations like health monitoring, data management, route information, stop searches, arrival times, alerts, and vehicle positions without being overwhelming or insufficient.

    Completeness4/5

    The toolset provides comprehensive coverage for real-time bus system queries, including data initialization, route and stop information, arrivals, alerts, and vehicle tracking. A minor gap exists in lacking update or deletion tools for data management, but this is reasonable for a read-focused transit API.

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables users to interact with Washington DC Metro (WMATA) transit system through natural language queries. Provides real-time train arrivals, service alerts, station information, trip planning, and accessibility updates.
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables real-time Chicago Transit Authority train and bus tracking, including arrivals, positions, and predictions for CTA 'L' trains and buses.
      56 npm
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      Provides live bus and light rail data for the Charlotte Area Transit System, including vehicle positions, arrivals, and route information via GTFS-Realtime feeds.
      3
      MIT