🛒 Pyaterochka MCP Tool

MCP-Server und KI-Bot für den Katalog «Пятёрочки» — findet Geschäfte, Produkte, Aktionen und Preise in ganz Russland, direkt aus Ihrer KI.

✨ Was ist das

Das Projekt verwandelt den öffentlichen Katalog von 5ka.ru in Tools für LLMs:

Er kann:

• 🔍 eine physische Filiale per Adresse oder Geolokalisierung finden;

• 🗂️ die Kategorien einer bestimmten Filiale abrufen;

• 🛒 Produkte mit Filtern durchsuchen: Preis (min/max), Marke, nur Aktionsartikel;

• 📊 nach Preis / Rabatthöhe / Beliebtheit sortieren;

• 💳 den Preis mit Kundenkarte, Aktionen „beim Kauf von N Stück“ und den alten Preis anzeigen;

• 📋 Verfügbarkeit, Restbestand, Nährwerte, Zusammensetzung, PLU und Produktlink zurückgeben;

• 📸 ein Fotoalbum der gefundenen Produkte in Telegram senden.

⚠️ Das Projekt ist inoffiziell und steht in keiner Verbindung zu X5 Group. Es nutzt darauf den offenen Webkatalog ohne Login und Passwort. Nur zu Bildungszwecken.

Related MCP server: E-Commerce MCP Server

🏗️ Architektur

                    ┌──────────────────────┐
                    │   Claude / Cursor /  │
                    │  ChatGPT / Telegram  │
                    └──────────┬───────────┘
                               │
              ┌────────────────┴────────────────┐
              │                                 │
     MCP stdio / HTTP MCP                OpenAI-compatible API
              │                                 │
    ┌─────────▼─────────┐             ┌─────────▼─────────┐
    │   mcp/mcp_server  │             │    llm_client     │
    │  + mcp_http_server│             │ (фолбэк между     │
    └─────────┬─────────┘             │  провайдерами)    │
              │                       └─────────┬─────────┘
    ┌─────────▼──────────────────────────────────▼─────────┐
    │                 pyaterochka_store_api                 │
    │   браузер Camoufox  ИЛИ  aiohttp + cookies.json       │
    └──────────────────────────┬───────────────────────────┘
                               │
                        🌐 5d.5ka.ru API

🚀 Schnellstart

1. Installation

git clone https://github.com/<you>/pyaterochka-mcp-tool.git
cd pyaterochka-mcp-tool

python -m venv .venv
# Windows:
.venv\Scripts\activate
# Linux/macOS:
source .venv/bin/activate

pip install -r requirements.txt

Ohne ihn funktioniert es ebenfalls — über Cookies (siehe unten). Mit ihm sind Cookies überhaupt nicht nötig:

pip install "camoufox[geoip]"
python -m camoufox fetch   # один раз скачать браузер (~150 МБ)

2. Konfiguration der .env

cp .env.example .env

Mindestanforderung für den MCP-Server: nichts (nur Cookies, wenn Sie camoufox nicht installieren). Mindestanforderung für den Bot:

TELEGRAM_BOT_TOKEN=123456:AA...      # от @BotFather
LLM_API_URL=https://api.openai.com/v1
LLM_API_KEY=sk-...
LLM_MODEL=gpt-4o-mini

Jeder OpenAI-kompatible Anbieter passt: OpenAI, OpenRouter, Groq DeepSeek, NVIDIA NIM, Together AI oder ein lokaler vLLM/Ollama (http://localhost:11434/v1).

🇷🇺 Für Nutzer in der Russischen Föderation: Wenn api.telegram.org offiziell nicht erreichbar ist, kannst du ein öffentliches Telegram-Bot-API-Spiegel verwenden — einfach in .env ergänzen:

TELEGRAM_API_BASE_URL=https://telegram.ebalo.lol

🧩 MCP-Server starten

Option A: stdio (für Desktop-Clients)

Das muss nicht manuell gestartet werden — der Client startet den Prozess selbst. Fügen Sie den Server zur Client-Konfiguration hinzu:

Claude Desktop — claude_desktop_config.json:

{
  "mcpServers": {
    "pyaterochka": {
      "command": "python",
      "args": ["C:/absolute/path/to/pyaterochka-mcp-tool/mcp/mcp_server.py"],
      "env": {
        "PYATEROCHKA_COOKIES_FILE": "C:/secrets/pyaterochka/cookies.json"
      }
    }
  }
}

Cursor / jeder Client mit mcpServers — identisch aufgebaut.

Manuelle Prüfung:

python mcp/mcp_server.py          # слушает JSON-RPC в stdin/stdout
# или после pip install -e . :
pyaterochka-mcp

Variante B: HTTP (Streamable HTTP)

python mcp_http_server.py         # → http://127.0.0.1:8765/mcp

Endpunkte: POST /mcp (JSON-RPC), GET /health, GET / (Info + Tool-Liste).

Beispielanfrage:

curl -X POST http://127.0.0.1:8765/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"find_store","arguments":{"address":"Москва, Кировоградская улица, 17"}}}'

🧰 verfügbare Tools (12)

Mehr dazu in mcp/README.md.

🤖 Telegram-Bot starten

python bot.py      # только бот
python run.py      # бот + HTTP MCP-сервер вместе (живой вывод в консоль)

Wie man den Bot benutzt:

1. /start → senden Sie dem Bot die Getposition (Büroklammer → 📍 Location) oder schreiben Sie die Adresse;

2. wählen Sie die gewünschte Filiale per Buttons;

3. Sie können fragen: „Milch bis 100 ₽ finden“, „Was ist bei Kaffee reduziert?“, „Öffnungszeiten?“;

4. Befehle: /reset — Speicher für die Sitzung, /stop — Ausführung abbrechen, /model — Modell im laufenden Betreib wechseln.

Der Bot verhält sich wie ein Agent: er ruft selbst die Tools in der Kette auf (Filiale finden → Produkte suchen → Aktionen prüfen → Fotos und Ergebnis anzeigen).

🍪 Cookies: Brauche ich wirklich eine

Es gibt zwei Transportwege zum Katalog — wählen Sie eine:

So bekommt ihr cookies.json (für die zweite Variante):

1. Öffnet 5ka.ru in Chrome/Firefox — Login isn’t necessary, es reicht, die Seite einfach zu öffnen;

2. Exportiert die Cookies per Erweiterung wie Get cookies.txt LOCALLY (Format JSON oder Netscape);

3. Speicher die Datei außerhalb des Repos, z.B. C:\secrets\pyaterochka\cookies.json;

4. Gib den Pfad an: PYATEROCHKA_COOKIES_FILE=C:\secrets\pyaterochka\cookies.json.

Beim Start ruft der Client zuerst 5ka.ru auf, um aktuelle schützende Cookies (spjs/spsc usw.) zu erhalten, und erneuert sie dann automatisch.

🔐 Veröffentlichen Sie cookies.json niemanden — das ist Ihre aktive Websession! Die Datei steht bereits in .gitignore. Falls sie verloren geht — bitte Cookies auf der Stelle löschen.

🌍 Öffentlicher Zugang: ChatGPT / Claude per Tunnel einbinden

Der HTTP-MCP-Server hört auf 127.0.0.1:8765 — damit externe KI-Anbieter (ChatGPT, Claude und alle Clients, die Remote MCP unterstützen) ihn erreichen können, die Anschluss bleibt im Tunnel:

ngrok:

ngrok http 8765
# получите адрес вида https://a1b2-...ngrok-free.app

cloudflared (ohne Registrierung):

cloudflared tunnel --url http://localhost:8765
# получите адрес вида https://....trycloudflare.com

Danach URL im Client ergänzen:

⚠️ Sicherheit: Der Endpunkt ist öffentlich und ohne Authentifizierung — jeder, der den Adresse kennt, kann Ihre Tools nutzen. Besonders im Dauerbetrieb den Tunnel hinter einen Reverse-Proxy legen oder ngrok mit IP-Einschränkung verwenden. Bewusst wurden SSH-Tunnel und Schlüssel unberücksichtigt in den Projekt-Code.

💡 Beispielabfragen

Найди в Пятёрочке по адресу Москва, Кировоградская улица, 17
молоко дешевле 200 рублей и отсортируй по цене.

Что из кофе сейчас по акции рядом со мной? Пришли фото топ-5.

Über die CLI (ohne KI):

python pyaterochka_store_api.py resolve --address "Москва, Кировоградская улица, 17"
python pyaterochka_store_api.py products --address "Москва, Кировоградская улица, 17" \
    --store-id S105 --query "молоко" --price-max 200 --sort price_asc --limit 20

📁 Projektstruktur

pyaterochka-mcp-tool/
├── mcp/
│   ├── mcp_server.py        # MCP stdio-сервер (12 инструментов)
│   └── README.md            # детали подключения MCP-клиентов
├── mcp_http_server.py       # HTTP (Streamable HTTP) транспорт MCP
├── pyaterochka_store_api.py # API-слой каталога 5ka.ru (+CLI)
├── bot.py                   # Telegram-бот (aiogram)
├── run.py                   # бот + HTTP MCP одним процессом
├── agent.py                 # агентский цикл: LLM ↔ инструменты
├── llm_client.py            # OpenAI-совместимый клиент с фолбэком
├── providers.py             # каталог LLM-провайдеров для /model
├── config.py                # конфиг из переменных окружения
├── stats.py / live_timer.py # статистика и консольные украшения
├── requirements.txt
├── pyproject.toml
└── .env.example

🛡️ Sicherheit

• Alle Schlüssel und Tokens — ausschließlich ruft die .env (geht nicht an Git).

• cookies.json, sessions.json, Logs — lie in .gitignore.

• Antworten des Models enthalten nie interne IDs (sap_code, .plu).

• Cookies, Proxies und Tokens nicht veröffentlichen — siehe Abschnitt Cookies.

⚖️ Lizenz

MIT. Das Projekt ist nicht mit X5 Group («Пятёрочка») verbunden; alle Namensrechte liegen bei ihren Inhabern.