Skip to main content
Glama
Pyaterochka MCP Tool

Pyaterochka MCP Tool

🛒 Pyaterochka MCP Tool

MCP-서버 및 AI-봇 for «Пятёрочка» (Пятёрочка) catalog — магазини, товарів, акцій і цін по всій России прямо з вашої нейронної мережі.

Python MCP Telegram License


✨ 이 프로젝트는 무엇인가요

이 프로젝트는 공개 카탈로그 5ka.ru를 LLM용 도구(tools) 로 변환합니다:

구성 요소

역할

🧩 MCP stdio 서버

Claude Desktop, Cursor, opencode 및 모든 MCP 클라이언트에서 작동합니다

🌐 HTTP MCP 서버

동일한 도구를 http://127.0.0.1:8765/mcp (Streamable HTTP)로 제공합니다 — 원격 MCP를 터널로 사용할 때 편리합니다

🤖 AI Telegram-봇

완전한 에이전트: 직접 매장을 찾고, 상품을 검색하며, 사진과 가격을 보여주고, 선호도를 기억합니다

할 수 있는 것:

  • 🔍 주소 또는 지리적 위치로 실제 점포를 검색;

  • 🗂️ 특정 매장의 카테고리 트리를 받아옴;

  • 🛒 필터(가격 최소/최대, 브랜드, 할인만)를 적용한 상품 검색;

  • 📊 가격 / 할인율 / 인기순으로 정렬;

  • 💳 카드 가격, "N개 구매 시" 할인, 이전 가격 표시;

  • 📋 재고, 잔여 수량, 단백질/지방/탄수화물, 구성, PLU 및 상품 링크 반환;

  • 📸 찾은 상품의 사진 앨범을 Telegram으로 전송.

⚠️ 이 프로젝트는 비공식이며 X5 Group과 관계가 없습니다. 로그인 없이 공개된 웹 카탈로그를 사용합니다. 학술적인 용도로만 사용하세요.


Related MCP server: supermercado

🏗️ 아키텍처

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

🚀 빠른 시작

1. 설치

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

브라우저 모드 없이도 동작합니다 — cookies를 사용합니다 (아래 참조). 브라우저 모드를 사용하면 cookies가 전혀 필요 없습니다:

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

2. .env 설정

cp .env.example .env

MCP 서버 동작을 위한 최소값 — 없음 (only cookies, if not camoufox). A бота의 최소값:

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

OpenAI 스펙의 대부분의 잘 제공됩니다: OpenAI, OpenRouter, Groq, DeepSeek, NVIDIA의 NIM, Deep AI, vLLM/Ollama (http://localhost:11434/v1).

변수

기본값

설명

TELEGRAM_BOT_TOKEN

—

@BotFather가 발급한 봇 토큰 (봇에 필수)

TELEGRAM_API_BASE_URL

https://api.telegram.org

로컬 Telegram Bot API Server를 지정하면 응답 스트리밍이 활성화됩니다

TELEGRAM_PROXY_SOCKS5

—

Telegram 전용 SOCKS5 프록시

LLM_API_URL

https://api.openai.com/v1

기본 LLM (OpenAI 호환 /v1)

LLM_API_KEY

—

기본 LLM의 API 키

LLM_MODEL

gpt-4o-mini

기본 공급자의 모델

LLM_RESERVE_URL/_KEY/_MODEL

—

예비 공급자 #1 (오류/429/5xx 발생 시 자동 전환)

LLM_FALLBACK_URL/_KEY/_MODEL

—

예비 공급자 #2 (마지막 대비)

OPENAI_API_KEY, OPENROUTER_API_KEY, GROQ_API_KEY, …

—

봇의 인라인 메뉴 /model 에 사용되는 API 키

PYATEROCHKA_COOKIES_FILE

—

cookies.json 경로 (브라우저 모드 미사용 시)

PYATEROCHKA_PROXY

—

5ka.ru 요청용 SOCKS5 프록시

MCP_HOST / MCP_PORT

127.0.0.1 / 8765

HTTP MCP-сервер адрес

🇷🇺 러시아 사용자: 공식 api.telegram.org 접근 불가 시 Telegram Bot API의 공개 미러를 사용할 수 있습니다 — .env에 다음을 추가하세요:

TELEGRAM_API_BASE_URL=https://telegram.ebalo.lol

🧩 MCP-сервер 시작

A: stdio (데스크톱 클라이언트용)

직접 시작할 필요가 없습니다 — 클라이언트가 프로세스를 직접 실행합니다. 클라이언트 설정 파일에 서버를 추가하세요:

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 / mcpServers를 지원하는 모든 클라이언트 — 형식은 동일합니다.

수동으로 확인하려면:

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

B: HTTP (Streamable HTTP)

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

엔드포인트: POST /mcp (JSON-RPC), GET /health, GET / (정보 및 도구 목록).

요청 예시:

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

🛠️ 사용 가능한 도구 (12)

도구

설명

find_store

주소로 매장 검색 → store_id 반환

find_nearest_stores

좌표로 가장 가까운 매장

get_store_info / get_store_hours

매장 정보 및 영업시간

list_stores_in_area

지정 영역 내 매장 목록

list_store_categories

매장 연체리

search_products

가격, 브랜드, 할인, 정렬 조건으로 상품 검색

list_category_products

카테고리 상품 검색 (필터 포함)

find_products

주소 또는 store_id로 통합 검색

get_product_promotion

상품별 프로모션 조건

get_product_info

상품 정보: 구성, 칼로리, 영양소

refresh_session

5ka.ru 웹 세션 갱신

자세한 사항은 mcp/README.md 참조.


🤖 Telegram-봇 시작

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

사용 방법:

  1. /start → 봇에게 위치(␐)를 보내거나 주소를 입력;

  2. 버튼으로 선택한 매장을 선택;

  3. 이렇게 질문해보세요: «우유 검색, 100₽ 이하», «커피에 할인 있나요?», «영업시간이 어떻게 되나요?»;

  4. 명령어: /reset — 메모리 초기화, /stop — 실행 중단, /model — 모델 변경.

봇은 에이전터로 동작합니다: 도구를 연결해서 독시 (매장 찾기 → 상품 검색 → 동적 할인 확인 → 사진과 최종 결과 표시).


🍪 Cookies: 필요한 이유와 사용법

카탈로그 접근을 위한 두 가지 방법 중 하나를 선택하세요:

🦊 브라우저 모드 (camoufox)

📄 aiohttp + cookies.json

수동 cookies

❌ 불필요

✅ 필요

403/anti-bot 대비 신뢰도

높음

낮음

의존성

무거움 (~150 MB 브라우저)

가벼움

cookies.json 생성 방법 (두 번째 방법):

  1. 5ka.ru를 Chrome/Firefox로 엽니다. 로그인이 필요 없습니다 — 그냥 사이트를 열기만 하면 됩니다;

  2. Get cookies.txt LOCALLY 같은 확장프로그램으로 cookies를 내보냅니다 (JSON 또는 Netscape 형식);

  3. 파일을 저장소 폴더 밖에 저장합니다. 예: C:\secrets\pyaterochka\cookies.json;

  4. 경로를 지정합니다: PYATEROCHKA_COOKIES_FILE=C:\secrets\pyaterochka\cookies.json.

시작 시 클라이언트는 먼저 5ka.ru를 열어 최신 보호 쿠키(spjs/spsc 등)를 얻고, 이후 자동으로 이를 갱신합니다.

🔐 cookies.json을 절대 공개하지 마세요 — 이 파일은 당신의 실제 웹 세션입니다. 파일은 이미 .gitignore에 포함되어 있습니다. 유출된 경우 사이트에서 쿠키를 초기화하세요.


🌍 공개 접근: ChatGPT / Claude를 터널로 연결

HTTP MCP-서버는 127.0.0.1:8765에서 수신됩니다. 외부 AI (ChatGPT, Claude 및 remote 메소드)가 접근하려면 아래와 같이 포트를 남겨두세요:

ngrok:

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

cloudflared (무료 가능):

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

클라이언트에 URL을 추가하세요:

클라이언트

추가하는 위치

Claude Desktop / Claude Web

Settings → Connectors → Custom connector → https://ваш-адрес/mcp

ChatGPT

Settings → Apps & Connectors → Create → URL https://ваш-адрес/mcp

Cursor

MCP settings → Add server → URL/SSE 타입

MCP Inspector

npx @modelcontextprotocol/inspector, transport: URL

⚠️ 보안 경고: 엔드포인트는 공개적이며 인증이 없습니다. 주소를 아는 사람은 누구 안 돼 도구를 사용할 수 있습니다. 지속적으로 사용하려면 리버스 프록시에서 기본 인증을 걸어주거나, IP 제한이 있는 ngrok을 사용하세요. SSH 터널/키는 프로젝트에 포함되지 않습니다.


💡 Query examples

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

CLI 이용 (AI 없이):

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

🛡️ 보안

  • 모든 키와 토큰은 .env를 통해서만 관리됩니다 (git에 항상되지 않음).

  • cookies.json, sessions.json, 로그 — .gitignore에 포함.

  • 모델의 답변은 절대 내부 id(sap_code, PLU)를 포함하지 않습니다.

  • cookies, proxy, 토큰을 공유하지 마세요 — Cookies 섹션 참조.

⚖️ License

MIT. Project not affiliated with X5 Group ("Пятёрочка"); all trademarks belong to their owners.

Available Tools

12 tools
find_nearest_storesB

Find nearby Pyaterochka stores by coordinates, sorted by distance.

Inputs: latitude (required), longitude (required), limit.

find_productsC

Find products by store_id or address, resolving the nearest store when needed.

Inputs: query (required), sort, brand, limit, +6 more.

find_storeB

Find the nearest Pyaterochka store for a full address and return its store_id.

Inputs: address (required).

get_product_infoB

Get product details by PLU, including ingredients, calories, nutrients and URL.

Inputs: plu (required), store_id (required).

get_product_promotionB

Get promotion details for a product PLU in a store.

Inputs: plu (required), store_id (required).

get_store_hoursB

Get opening hours and 24-hour status for a store by store_id.

Inputs: store_id (required).

get_store_infoB

Get store details by store_id, including address, opening hours, metro and coordinates.

Inputs: store_id (required).

list_category_productsC

List products in a store category and apply filters.

Inputs: store_id (required), category_id (required), sort, brand, +5 more.

list_store_categoriesC

Get the category tree for a store.

Inputs: store_id (required).

list_stores_in_areaC

List Pyaterochka stores inside a rectangular map area.

Inputs: top_latitude (required), left_longitude (required), bottom_latitude (required), right_longitude (required).

refresh_sessionB

Refresh the protective cookies for the current 5ka.ru web session.

Inputs: no named parameters.

search_productsC

Search products in a store and apply price, brand, promotion and sorting filters.

Inputs: query (required), store_id (required), sort, brand, +5 more.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    C2.9/5.0

    Scored across 12 tools

    Disambiguation3/5

    Several tools overlap in purpose: find_store, find_nearest_stores, and list_stores_in_area all retrieve store locations but with different inputs, while get_store_info and get_store_hours both provide hours (though get_store_info is more comprehensive). Similarly, search_products, list_category_products, and find_products all search products with overlapping filters, which could cause misselection. The descriptions help but are not always enough to clearly distinguish the best tool.

    Naming Consistency2/5

    Tool names use a mix of verbs (refresh, find, get, list, search) without a consistent convention. Some are find_* (e.g., find_store, find_nearest_stores), some get_* (get_store_info, get_store_hours), some list_* (list_stores_in_area, list_store_categories), and some search_* (search_products). This mixed style makes it harder to predict tool names from intent, though the noun part is generally clear.

    Tool Count5/5

    With 12 tools covering store lookup, store details, product search, categories, promotions, and session management, the count is well-scoped for the domain. Each tool has a distinct role, and there are enough tools to represent the core API surface without being overwhelming.

    Completeness4/5

    The tool set covers the typical read-only operations for a grocery store API: finding stores, retrieving store info, searching products, filtering by category and promotion, and getting product details. Minor gaps exist (e.g., no tool for store reviews or a direct list-all-products endpoint), but the main workflows users would expect are well covered.

    Maintenance

    ActivityNo data
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      B
      maintenance
      Provides MCP tools to search products, check stock, and retrieve store information from the GTA7 Lab supermarket entity.
      -
    • A
      license
      B
      quality
      C
      maintenance
      Enables LLM-driven interaction with the GLOBUS online store, including product search, catalog browsing, product details, promotions, recommendations, and anonymous shopping cart management via MCP.
      22
      MIT