# 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
```bash
# 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):
```json
{
"mcpServers": {
"riyadh-districts": {
"command": "/path/to/project/.venv/bin/python",
"args": ["-m", "src.main"],
"cwd": "/path/to/project"
}
}
}
```
### As HTTP Server
```bash
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)
```bash
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](https://github.com/alioh/Saudi-Districts-Dataset).
## License
MIT
