🛒 Pyaterochka MCP Tool

MCP server and AI bot for the Pyaterochka catalog — search for stores, products, promotions, and prices across Russia right from your neural network.

✨ What this is

The project turns the public catalog of 5ka.ru into tools for LLMs:

Capabilities:

• 🔍 find a physical store by address or geolocation;

• 🗂️ get categories of a specific store;

• 🛒 search products with filters: price (min/max), brand, promotions only;

• 📊 sort by price / discount size / popularity;

• 💳 show the card price, "buy N items" promotions, the old price;

• 📋 return availability, stock, nutritional values, ingredients, PLU, and a product link;

• 📸 send a photo album of found products in Telegram.

⚠️ The project is unofficial and not affiliated with X5 Group. It uses the open web catalog without login or password. For educational purposes only.

Related MCP server: supermercado

🏗️ Architecture

                    ┌──────────────────────┐
                    │   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

🚀 Quick start

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

It works without it too — via cookies (see below). With it, cookies are not needed at all:

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

2. Setting up .env

cp .env.example .env

The minimum for the MCP server to work is nothing (only cookies, if you didn't install camoufox). The minimum for the bot:

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

Any OpenAI-compatible provider will work: OpenAI, OpenRouter, Groq, DeepSeek, NVIDIA NIM, Together AI, local vLLM/Ollama (http://localhost:11434/v1).

🇷🇺 For users in Russia: if the official api.telegram.org is unavailable, you can use a public Telegram Bot API mirror — just add to .env:

TELEGRAM_API_BASE_URL=https://telegram.ebalo.lol

🧩 Running the MCP server

Option A: stdio (for desktop clients)

No need to run anything manually — the client starts the process itself. Add the server to the client config:

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 / any client with mcpServers — the format is the same.

You can check manually like this:

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

Option B: HTTP (Streamable HTTP)

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

Endpoints: POST /mcp (JSON-RPC), GET /health, GET / (info + list of tools).

Example request:

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"}}}'

🧰 Available tools (12)

More details in mcp/README.md.

🤖 Running the Telegram bot

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

How to use:

1. /start → send the bot your geolocation (paperclip → 📍 Location) or type an address;

2. choose your favorite store with the buttons;

3. ask: "find milk under 100 ₽", "what's on sale for coffee?", "opening hours?";

4. commands: /reset — reset memory, /stop — interrupt execution, /model — switch models on the fly.

The bot behaves like an agent: it calls tools in a chain on its own (find store → search products → check promotions → show photos and the summary).

🍪 Cookies: are they needed and why

There are two transports for accessing the catalog — pick one:

How to get cookies.json (for the second option):

1. Open 5ka.ru in Chrome/Firefox — no login needed, just open the site;

2. Export cookies with an extension like Get cookies.txt LOCALLY (JSON or Netscape format);

3. Save the file outside the repository, e.g. C:\secrets\pyaterochka\cookies.json;

4. Specify the path: PYATEROCHKA_COOKIES_FILE=C:\secrets\pyaterochka\cookies.json.

On startup, the client first opens 5ka.ru to accept fresh protective cookies (spjs/spsc and others), then updates them automatically.

🔐 Never publish cookies.json — it's your live web session. The file is already added to .gitignore. If it leaks — clear the cookies on the site.

🌍 Public access: connecting ChatGPT / Claude via a tunnel

The HTTP MCP server listens on 127.0.0.1:8765 — for external neural networks (ChatGPT, Claude, and any clients with remote MCP support) to reach it, wrap the port in a tunnel:

ngrok:

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

cloudflared (no registration):

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

Then add the URL to the client:

⚠️ Security: the endpoint is public and without authentication — anyone who learns the address can use your tools. For permanent use, protect the tunnel with basic authentication on a reverse proxy or use ngrok with IP restrictions. SSH tunnels/keys are deliberately not included in the project code.

💡 Example queries

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

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

Via CLI (without a neural network):

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

📁 Project structure

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

🛡️ Security

• All keys and tokens — only via .env (never gets into git).

• cookies.json, sessions.json, logs — in .gitignore.

• Model responses never contain internal ids (sap_code, PLU).

• Don't publish cookies, proxies, or tokens — see the Cookies section.

⚖️ License

MIT. The project is not affiliated with X5 Group (Pyaterochka); all trademarks belong to their owners.