madurai-transit-mcp
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@madurai-transit-mcp Find a bus route from Periyar to Mattuthavani."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
🚌 Madurai CityBus Model Context Protocol (MCP) Server
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.jsonWindows:
%APPDATA%\Claude\claude_desktop_config.jsonLinux:
~/.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:
Headway Frequency vs. Timetables: TNSTC Madurai buses operate on shift-based headway frequency rather than published minute-by-minute digital timetables.
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.
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
Web App & Live Bus Telemetry: https://maduraione.in
Android App (Google Play): Madurai CityBus on Google Play
GitHub Repository: https://github.com/rsiva2294/madurai-transit-mcp
📄 License
MIT © MaduraiOne
Available Tools
4 toolscalculate_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
Scored across 4 tools
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.
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.
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.
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
Related MCP Connectors
Mobility, geocoding and nearby urban services for AI agents.
Real-time transit stops, routes, arrivals, vehicle positions, and schedules via OneBusAway APIs.
Provide real-time transportation data including bus arrivals, train service alerts, carpark availa…
Routing, geocoding, places, matrix and map tools for location-aware AI workflows.
Related MCP Servers
- AlicenseBqualityDmaintenanceProvides real-time Transport for London journey data, including routes, alerts, and disruptions, allowing AI assistants to search journeys and get station information.18 npm4ISC
- FlicenseNot gradedqualityDmaintenanceProvides real-time Singapore bus information, including arrival times, routes, and stop details via the LTA DataMall API.1-
- AlicenseNot gradedqualityBmaintenanceEnables local AI clients to search Houston METRO routes, stops, nearby stops, realtime arrivals, and service alerts through natural language.MIT
- AlicenseAqualityCmaintenanceEnables 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.101MIT