An implementation of a Model Context Protocol (MCP) server for Bangalore Metropolitan Transport Corporation (BMTC) bus services.
The BMTC MCP server follows a modular, layered architecture. The system is designed to handle real-time transit data from Bangalore Metropolitan Transport Corporation buses and provide it through a standardized API.
- API Layer: RESTful endpoints for authentication, routes, stops, bus locations, and ETA information
- Service Layer: Business logic, data transformation, and ETA calculations
- Data Access Layer: MongoDB integration via Mongoose ODM
- Caching Layer: Redis-based caching for improved performance
- External Integration Layer: BMTC API integration
Read the full architecture documentation
Here're the list of things that you can find using MCP Client or chat window:
- Real-time bus location tracking
- Route information and scheduling
- Stop details and ETA (Estimated Time of Arrival)
- Support for over 2,200 bus routes and 8,400+ bus stops in Bengaluru
- Authentication and authorization
- Data caching and optimization
- GeoSpatial queries for nearby stops and buses
- Node.js (v14 or later)
- npm or yarn
- MongoDB
- Redis (optional, for caching)
- Git
- Clone the repository
git clone https://github.com/ajeetraina/bengaluru-bmtc-mcp.git
cd bengaluru-bmtc-mcp- Install dependencies
npm install- Configure environment variables
cp .env.example .envEdit the .env file with your configuration:
PORT=3000
NODE_ENV=development
MONGO_URI=mongodb://localhost:27017/bmtc-mcp
REDIS_URI=redis://localhost:6379
API_KEY=your_api_key_here
JWT_SECRET=your_jwt_secret_here
JWT_EXPIRES_IN=86400
BMTC_API_ENDPOINT=https://bmtc-api-endpoint.example
BMTC_API_KEY=your_bmtc_api_key_here
CACHE_DURATION=300
LOG_LEVEL=info
- Seed the database with mock data (optional)
node src/scripts/seed.js- Start the server
npm startFor development with auto-restart:
npm run dev- Clone the repository
git clone https://github.com/ajeetraina/bengaluru-bmtc-mcp.git
cd bengaluru-bmtc-mcp- Configure environment variables (optional)
You can modify the environment variables directly in the docker-compose.yml file or create a .env file:
cp .env.example .env- Build and start the containers
docker-compose up -dThis will start three containers:
bmtc-mcp-api: The Node.js API serverbmtc-mcp-mongo: MongoDB databasebmtc-mcp-redis: Redis cache server
- Seed the database with mock data (optional)
docker-compose exec api node src/scripts/seed.js- View logs
docker-compose logs -f api- Stop the containers
docker-compose downTo remove volumes as well:
docker-compose down -vOnce the server is running, you can access the API at:
http://localhost:3000/api/v1
For API documentation, visit:
http://localhost:3000/api-docs
# Authentication
POST /api/v1/auth/login
GET /api/v1/auth/me
# Routes
GET /api/v1/routes
GET /api/v1/routes/:routeId
GET /api/v1/routes/search?source=Kempegowda&destination=Electronic
# Stops
GET /api/v1/stops
GET /api/v1/stops/:stopId
GET /api/v1/stops/near?lat=12.9767&lng=77.5713&radius=500
GET /api/v1/stops/search?query=Lalbagh
# Bus Locations
GET /api/v1/bus-locations
GET /api/v1/bus-locations/:busId
GET /api/v1/bus-locations/near?lat=12.9767&lng=77.5713&radius=1000
# ETA
GET /api/v1/eta/:stopId
GET /api/v1/eta/:stopId/:routeId
The JWT secret is used for signing authentication tokens. Generate a secure random string:
node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"Add this to your .env file:
JWT_SECRET=your_generated_secret_here
For development, you can use mock data without an actual BMTC API key:
BMTC_API_ENDPOINT=https://bmtc-api-endpoint.example
BMTC_API_KEY=your_bmtc_api_key_here
For production, you would need to contact BMTC directly to request official API access.
Run the tests:
npm testRun tests with coverage:
npm run test:coverageCheck code style:
npm run lintFix code style issues:
npm run lint:fixbengaluru-bmtc-mcp/
├── .env.example # Environment variables template
├── .eslintrc.json # ESLint configuration
├── .github/ # GitHub configuration
│ └── workflows/ # GitHub Actions workflows
├── .gitignore # Git ignore file
├── CONTRIBUTING.md # Contribution guidelines
├── Dockerfile # Docker configuration
├── LICENSE # MIT License
├── README.md # Project documentation
├── docker-compose.yml # Docker Compose configuration
├── docs/ # Documentation
│ ├── api.md # API documentation
│ └── setup.md # Setup guide
├── jest.config.js # Jest configuration
├── package.json # Project dependencies
└── src/ # Source code
├── config/ # Configuration files
├── controllers/ # Request handlers
├── index.js # Application entry point
├── middlewares/ # Express middlewares
├── models/ # MongoDB models
├── public/ # Static files
├── routes/ # API routes
├── scripts/ # Utility scripts
├── services/ # External service integrations
├── tests/ # Test files
└── utils/ # Utility functions
Please read CONTRIBUTING.md for details on our code of conduct and the process for submitting pull requests.
This project is licensed under the MIT License - see the LICENSE file for details.