Riyadh Districts MCP Server

An MCP (Model Context Protocol) server that provides tools for finding distances between districts in Riyadh, Saudi Arabia.

Features

192 Riyadh districts with coordinates
Arabic & English name support with normalization
5 MCP tools for querying district data
Distance calculation using Haversine formula

MCP Tools

Tool	Description
`get_nearest_districts`	Get top N nearest districts to a given district
`get_distance_between_districts`	Calculate distance (km) between two districts
`list_all_districts`	List all available Riyadh districts
`search_districts`	Search districts by partial name (Arabic/English)
`get_district_info`	Get district details including coordinates

Installation

# Clone the repository
git clone https://github.com/YOUR_USERNAME/riyadh-districts-mcp.git
cd riyadh-districts-mcp

# Create virtual environment and install dependencies
uv venv
source .venv/bin/activate
uv pip install -r requirements.txt

Usage

As MCP Server (for Cursor/Claude)

Add to your MCP configuration (.cursor/mcp.json or Claude Desktop config):

{
  "mcpServers": {
    "riyadh-districts": {
      "command": "/path/to/project/.venv/bin/python",
      "args": ["-m", "src.main"],
      "cwd": "/path/to/project"
    }
  }
}

As HTTP Server

source .venv/bin/activate
uvicorn src.main:app --host 0.0.0.0 --port 4501 --reload

Health check: http://localhost:4501/health

CLI Usage (Legacy)

python main.py "Al Olaya" --top 10
python main.py --distance "Al Olaya" "Al Yasmin"
python main.py --list

Data Source

District data sourced from alioh/Saudi-Districts-Dataset.

License

MIT

districts-mcp