kharkiv-metro-rp

Kharkiv Metro MCP server provides programmatic access to the Kharkiv metro route planner features. It exposes tools for finding routes, querying station schedules, listing all stations, and searching for a station by name, which can be integrated into AI assistants or other automation workflows. The MCP server uses the same core data and routing logic as the CLI and Telegram bot, but presents a lightweight, programmatic API facade suitable for integration with chat assistants or other automation tasks. You can rely on the get_route command to obtain optimal paths between two stations, the get_schedule command to fetch a station’s timetable, list_stations to retrieve the full list of stations, and find_station to locate a station by name or alias. The server is designed to work offline with a local database and to scrape schedule data from metro.kharkiv.ua during initialization or as configured.

Prerequisites:

• Python 3.11+ installed on your system
• uv runtime available (as used by this MCP setup; see below)
• Access to install dependencies (pip or pipx)

Installation steps:

1. Clone or download the repository containing the Kharkiv Metro components, or install the MCP package if published:

   • git clone https://github.com/your-org/kharkiv-metro-rp.git
   • cd kharkiv-metro-rp

2. Install the uv runtime and dependencies. If uv is provided via pipx:

   • python3 -m pip install --user pipx
   • pipx install uv (Alternatively install uv through your preferred Python package manager as documented in your environment.)

3. Install Python dependencies for the core and MCP server:

   • python3 -m pip install -r requirements.txt
   • python3 -m pip install -r mcp/requirements.txt

4. Initialize the local database and scrape schedules (requires network access):

   • uv run metro --init-db
   • uv run metro

5. Run the MCP server (example):

   • uv run metro-mcp
   • This starts the MCP server exposing commands: get_route, get_schedule, list_stations, find_station

Notes:

• If you prefer to run via a script path, ensure the entrypoint script metro-mcp is in your PATH or reference it directly in the uv run command.
• You may configure environment variables for paths to the local database or analytics store as described in the project documentation.

Tips and common issues:

• Ensure Python 3.11+ and network access for initial schedule scraping from metro.kharkiv.ua.
• The MCP server stores data in a local SQLite database; check the configured path in your config.toml if you customize storage.
• If you need to persist analytics data across redeployments, set ANALYTICS_DB_PATH to a persistent location and restart the server.
• When using the MCP API, consider time zone implications (TZ) to ensure route times align with local Kyiv time.
• If you update station data or schedules, re-run initialization or trigger a data refresh to keep the MCP in sync with the latest information.