MCP Hkbus

🚀 Hong Kong Kowloon Motor Bus (KMB) and Long Win Bus (LWB) MCP Server

A Model Context Protocol (MCP) server that provides real-time route information and estimated arrival times for Hong Kong Kowloon Motor Bus (KMB) and Long Win Bus (LWB). This server enables language models to query Hong Kong bus service information to answer users' questions about bus routes, stops, and estimated arrival times.

✨ Features

• Real-time bus estimated arrival times (ETA)
• Comprehensive bus route search
• Bus stop information and search
• Mapping of routes to stops
• Caching system to optimize API calls
• Bilingual support (English and Traditional Chinese)

📦 Data Sources

This project uses the official KMB/LWB open data API:

• Base URL: https://data.etabus.gov.hk/v1/transport/kmb
• KMB Open Data API Documentation

📋 Dependencies

• Python 3.10 or higher
• uv package manager

📦 Installation

Step 1: Install uv (if not already installed)

curl -LsSf https://astral.sh/uv/install.sh | sh

Step 2: Clone the repository

git clone git@github.com:kennyckk/mcp_hkbus.git
cd mcp_hkbus

Step 3: Handle Python packages with uv

uv sync # Use uv.lock

💻 Usage Examples

Basic Usage

Edit the configuration of your MCP client (e.g., Claude Desktop):

{
  "mcpServers": {
    "bus_service": {
      "command": "path/to/uv.exe",
      "args": ["--directory", "path/to/kmb_bus", "run", "kmb_mcp.py"],
      "background": true
    }
  }
}

Advanced Usage

The server provides several tools for language models to query bus information:

• get_route_list(): Get a list of all bus routes.
• get_stop_list(): Get a list of all bus stops.
• get_route_stops(): Get the stops for a specific route.
• find_stops_by_name(): Search for bus stops by name.
• get_all_routes_at_stop(): Get all routes serving a specific stop.
• get_eta(): Get estimated arrival times.

🧪 Testing

Run the test suite using pytest:

pytest test/kmb-mcp-tests.py

📚 Dependencies

• httpx: For asynchronous HTTP requests.
• fastmcp: For MCP server implementation.
• pytest: For testing (development environment).

🤝 Contributing

Everyone is welcome to contribute! Please feel free to submit a pull request.

🙏 Special Thanks

• KMB/LWB for providing the open data API.
• The developers of the MCP protocol.

⚠️ Important Note

This service relies on the KMB/LWB open data API. Please be aware of the API's rate limits and implement appropriate error handling in a production environment.