gdebenz-mcp

MCP-сервер для поиска бензина и дизеля на АЗС России. Объединяет два независимых источника — gdebenz.ru и gdebenzi.ru — народные карты наличия топлива с отметками водителей в реальном времени.

Позволяет вашему ИИ-ассистенту (Claude, Cursor, OpenClaw и др.) отвечать на вопросы вроде:

«Где рядом с Химками есть 95-й бензин?» «Какая ближайшая заправка Лукойл с дизелем, и есть ли там очередь?»

Работает через публичные API обоих сервисов. Без API-ключей — нужен только Python и два пакета.

Два источника данных

Источник	Что даёт
gdebenz	статус наличия, список топлива, подтверждения, свежесть (last_at), уверенность, цены
gdebenzi	статус, текст очереди («очередь 25–50 авто»), лимиты (л), подтверждённое топливо (fuels_yes/no), средние цены региона, отметки/отчёты

У инструментов поиска есть параметр source: "gdebenz", "gdebenzi" или "both" (по умолчанию both — максимум покрытия).

---

Установка

1. Склонируй репозиторий

git clone https://github.com/ivanegorenkov/gdebenz-mcp.git
cd gdebenz-mcp

2. Установи зависимости

pip install -r requirements.txt

Нужен Python 3.10+.

3. Подключи сервер к своему ассистенту

Claude Desktop — открой/создай claude_desktop_config.json:

{
  "mcpServers": {
    "gdebenz": {
      "command": "python3",
      "args": ["/АБСОЛЮТНЫЙ/ПУТЬ/gdebenz-mcp/server.py"]
    }
  }
}

Cursor — в .cursor/mcp.json проекта (или глобальный ~/.cursor/mcp.json):

{
  "mcpServers": {
    "gdebenz": {
      "command": "python3",
      "args": ["/АБСОЛЮТНЫЙ/ПУТЬ/gdebenz-mcp/server.py"]
    }
  }
}

OpenClaw:

openclaw mcp add gdebenz --command python3 --arg /АБСОЛЮТНЫЙ/ПУТЬ/gdebenz-mcp/server.py

⚠️ Замените /АБСОЛЮТНЫЙ/ПУТЬ/ на реальный путь, куда склонирован репозиторий (узнать можно командой pwd внутри папки).

---

Инструкция для ИИ-агента

Если пользователь просит «поставь этот MCP-сервер» — сделай следующее:

1. git clone https://github.com/ivanegorenkov/gdebenz-mcp.git
2. cd gdebenz-mcp && pip install -r requirements.txt
3. Определи MCP-хост пользователя (Claude Desktop / Cursor / OpenClaw) и добавь запись gdebenz в его конфиг, как показано выше (с абсолютным путём к server.py).
4. Перезапусти хост/приложение.
5. Проверь, что сервер виден (в OpenClaw: openclaw mcp probe gdebenz).

Сервер stdio, внешних ключей не требует.

---

Что умеет (9 инструментов)

Инструмент	Что делает
find_fuel	Главный. Заправки с топливом рядом с местом (по названию или координатам). Фильтры: топливо, сеть, статус, радиус, source. Сортировка по расстоянию.
nearby_stations	Заправки вокруг точки (lat/lon + радиус + source).
stations_with_prices	Заправки в области + цены (bbox + source).
search_stations	Поиск заправки по названию/адресу.
resolve_location	Название места → координаты.
get_geoip_location	Моё местоположение по IP.
get_city_by_coords	Город по координатам.
list_fuels	Марки топлива: 92 / 95 / 98 / 100 / ДТ.
list_brands	Частые сети АЗС (фильтр принимает любую строку).

Пример запроса к ассистенту: find_fuel(location="Химки", fuel="95", brand="Лукойл", source="both").

Семантика

• Топливо: 92, 95, 98, 100, ДТ. У gdebenz — fuels_now (строка через запятую), у gdebenzi — fuels_yes / fuels_no / fuels_maybe (массивы с русскими названиями, напр. ["АИ-95", "ДТ"]).
• Статус: yes — есть, queue — есть/очередь, low — мало, no — нет, unknown — неизвестно, changing — обновляется, dtonly — только дизель.
• Актуальность: у gdebenz — last_at, confirmations, confidence (0..1); у gdebenzi — last_mark (время отметки), confidence_pct, marks, reports. Оба источника отдают age_minutes и freshness («только что», «3 ч назад»).
• Очередь/лимиты (gdebenzi): queue («очередь 25–50 авто»), limits (лимит в литрах на марку).
• Цены: gdebenz — prices_now[fuel].t (время отчёта о цене); gdebenzi — prices (ключи ai92/ai95/ai98/ai100/dt/gas) и regional_prices (средние по региону).

API (откуда данные)

gdebenz.ru

Endpoint	Назначение
GET /api/nearby?lat=&lon=&radius_km=	станции вокруг точки
GET /api/stations?lat1=&lon1=&lat2=&lon2=	станции в bbox + цены
GET /api/search?q=	текстовый поиск
GET /api/cities?q=	геокодинг
GET /api/geoip	местоположение по IP
GET /api/reverse-city?lat=&lon=	город по координатам

gdebenzi.ru

Endpoint	Назначение
GET /api/stations.php?bbox=lon1,lat1,lon2,lat2	станции в bbox (статус, очередь, лимиты, цены, отметки)

Лицензия

MIT