Skip to main content
Glama

🚌 Madurai CityBus Model Context Protocol (MCP) Server

npm version rsiva2294/madurai-transit-mcp MCP server License: MIT Powered by MaduraiOne

The official Model Context Protocol (MCP) server for Madurai CityBus public transit, connecting AI assistants (Claude Desktop, Cursor, Gemini, AI Agents) to Madurai's bus route network, official stage fares, stop sequences, and platform bay departures.


⚡ Features

  • Route Discovery: Direct and 1-transfer routing across 966 bus routes and 3,000 stops in Madurai.

  • Official Stage Fares: Authoritative TNSTC stage fare breakdowns (Ordinary, LSS, Express, Deluxe AC).

  • Platform Bay Intelligence: Departure platforms (I/II/III/IV) at Periyar Bus Stand.

  • Bilingual Stop Search: Search stops in English, Tamil Unicode (பெரியார்), or colloquial transliterations.

  • Interactive Deep Links: Automatically returns canonical links (https://maduraione.in/route/...) for live visual route maps.


Related MCP server: Singapore Bus MCP Server

🚀 Quick Setup

1. Claude Desktop

Add this configuration to your claude_desktop_config.json:

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

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

  • Linux: ~/.config/Claude/claude_desktop_config.json

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

2. Cursor IDE

Add this to .cursor/mcp.json or in Cursor Settings ➔ Features ➔ MCP:

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

3. Local Testing with MCP Inspector

You can test all tools interactively using the official MCP Inspector:

npx @modelcontextprotocol/inspector npx -y madurai-transit-mcp

🛠️ Available MCP Tools

search_bus_routes

Find direct and 1-transfer bus routes between two locations in Madurai.

{
  "from": "Periyar",
  "to": "Alagarkovil",
  "max_transfers": 1
}

get_bus_details

Get full route details, spoke category, departure platform bay, and complete stop sequence for a specific bus number.

{
  "bus_number": "44"
}

search_bus_stops

Bilingual search (English & Tamil) for bus stops with spoke classifications and verified GPS coordinates.

{
  "query": "பெரியார்"
}

calculate_fare

Calculate exact official TNSTC stage fares across all service classes (Ordinary, LSS, Express, Deluxe AC).

{
  "boarding_stop": "PERIYAR BUS STAND",
  "alighting_stop": "MGR BUS STAND",
  "bus_number": "77"
}

⚠️ Ground Realities & Disclaimers

Public transit in Tier-2 Indian cities operates differently from Western transit models:

  1. Headway Frequency vs. Timetables: TNSTC Madurai buses operate on shift-based headway frequency rather than published minute-by-minute digital timetables.

  2. Topological vs. Surveyed GPS: Out of ~3,000 stops across the district, ~600 core urban stops have verified survey coordinates. Remaining rural/peri-urban stops are mapped topologically by sequence.

  3. Multi-Leg Transfers: Interchange suggestions use the 7-Spoke Madurai Topological Model and should be treated as guidance. Commuters should verify live platform departures at bus stands.


🌐 Powered By


📄 License

MIT © MaduraiOne

Available Tools

4 tools
calculate_fareB

Calculate the official TNSTC stage fare between any boarding and alighting bus stop in Madurai across Ordinary, LSS, Express, and Deluxe/AC classes based on authoritative stage charts.

Inputs: boarding_stop (required), alighting_stop (required), bus_number.

get_bus_detailsA

Lookup route details, platform bay at Periyar Bus Stand, spoke category, and stop sequence for a specific Madurai bus number (e.g. '44', '77', '11A', '5'). By default returns key transit milestones for token efficiency; set verbose=true for the complete numbered stop list.

Inputs: bus_number (required), verbose.

search_bus_routesA

Search bus routes between two stops in Madurai. Returns direct buses and 1-transfer options with stop counts, PBS platform bays, official TNSTC stage fares, and canonical visual map links. By default returns key milestones for token efficiency; set verbose=true for complete stop sequences.

Inputs: to (required), from (required), verbose, max_transfers.

search_bus_stopsA

Bilingual (English and Tamil) autocomplete and search for bus stops across Madurai. Returns canonical name, Tamil script name, spoke corridor, route frequency, and verified GPS coordinates if available.

Inputs: query (required).

Tool Schema Changelog

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

Loading tool schema changelog…

    TDQS

    A4/5.0

    Scored across 4 tools

    Disambiguation5/5

    Each tool has a clearly distinct purpose: finding routes between stops, retrieving details for a specific bus number, searching stops, and calculating fares. No overlapping functionality, so an agent can easily select the right tool.

    Naming Consistency5/5

    All tool names follow a consistent verb_noun pattern in snake_case (search_bus_routes, get_bus_details, search_bus_stops, calculate_fare). This creates a predictable and uniform naming convention.

    Tool Count5/5

    With only 4 tools, the server is well-scoped for its narrow domain of Madurai bus transit. Each tool serves a necessary function, and the count is within the ideal 3-15 range.

    Completeness4/5

    The tool surface covers the core transit workflows: route search, bus details, stop lookup, and fare calculation. Missing features like schedule or real-time tracking are not implied by the domain scope, so only minor gaps exist.

    Maintenance

    ActivityNo data
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      B
      quality
      D
      maintenance
      Provides real-time Transport for London journey data, including routes, alerts, and disruptions, allowing AI assistants to search journeys and get station information.
      1
      8 npm
      4
      ISC
    • A
      license
      A
      quality
      C
      maintenance
      Enables AI assistants to query live arrivals, vehicle positions, routes, stops, and timetables across the Athens public transport network, with stop lookups by name or coordinate in Greek or Latin script. Results cover OASA buses, trolleys, metro, and tram, falling back to cached reference data when the upstream API is unreachable.
      10
      1
      MIT