Pyaterochka MCP Tool
🛒 Pyaterochka MCP Tool
MCP-서버 및 AI-봇 for «Пятёрочка» (Пятёрочка) catalog — магазини, товарів, акцій і цін по всій России прямо з вашої нейронної мережі.
✨ 이 프로젝트는 무엇인가요
이 프로젝트는 공개 카탈로그 5ka.ru를 LLM용 도구(tools) 로 변환합니다:
구성 요소 | 역할 |
🧩 MCP stdio 서버 | Claude Desktop, Cursor, opencode 및 모든 MCP 클라이언트에서 작동합니다 |
🌐 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 .envMCP 서버 동작을 위한 최소값 — 없음 (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-miniOpenAI 스펙의 대부분의 잘 제공됩니다: OpenAI, OpenRouter, Groq, DeepSeek, NVIDIA의 NIM, Deep AI, vLLM/Ollama (http://localhost:11434/v1).
변수 | 기본값 | 설명 | |||
| — |
| |||
|
| 로컬 Telegram Bot API Server를 지정하면 응답 스트리밍이 활성화됩니다 | |||
| — | Telegram 전용 SOCKS5 프록시 | |||
|
| 기본 LLM (OpenAI 호환 | |||
| — | 기본 LLM의 API 키 | |||
|
| 기본 공급자의 모델 | |||
| — | 예비 공급자 #1 (오류/429/5xx 발생 시 자동 전환) | |||
| — | 예비 공급자 #2 (마지막 대비) | |||
| — | 봇의 인라인 메뉴 | |||
| — | cookies.json 경로 (브라우저 모드 미사용 시) | |||
| — | 5ka.ru 요청용 SOCKS5 프록시 | |||
|
| 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-mcpB: 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)
도구 | 설명 |
| 주소로 매장 검색 → |
| 좌표로 가장 가까운 매장 |
| 매장 정보 및 영업시간 |
| 지정 영역 내 매장 목록 |
| 매장 연체리 |
| 가격, 브랜드, 할인, 정렬 조건으로 상품 검색 |
| 카테고리 상품 검색 (필터 포함) |
| 주소 또는 |
| 상품별 프로모션 조건 |
| 상품 정보: 구성, 칼로리, 영양소 |
| 5ka.ru 웹 세션 갱신 |
자세한 사항은 mcp/README.md 참조.
🤖 Telegram-봇 시작
python bot.py # только бот
python run.py # бот + HTTP MCP-сервер вместе (живой вывод в консоль)사용 방법:
/start→ 봇에게 위치(␐)를 보내거나 주소를 입력;버튼으로 선택한 매장을 선택;
이렇게 질문해보세요: «우유 검색, 100₽ 이하», «커피에 할인 있나요?», «영업시간이 어떻게 되나요?»;
명령어:
/reset— 메모리 초기화,/stop— 실행 중단,/model— 모델 변경.
봇은 에이전터로 동작합니다: 도구를 연결해서 독시 (매장 찾기 → 상품 검색 → 동적 할인 확인 → 사진과 최종 결과 표시).
🍪 Cookies: 필요한 이유와 사용법
카탈로그 접근을 위한 두 가지 방법 중 하나를 선택하세요:
🦊 브라우저 모드 (camoufox) | 📄 aiohttp + cookies.json | |
수동 cookies | ❌ 불필요 | ✅ 필요 |
403/anti-bot 대비 신뢰도 | 높음 | 낮음 |
의존성 | 무거움 (~150 MB 브라우저) | 가벼움 |
cookies.json 생성 방법 (두 번째 방법):
5ka.ru를 Chrome/Firefox로 엽니다. 로그인이 필요 없습니다 — 그냥 사이트를 열기만 하면 됩니다;
Get cookies.txt LOCALLY 같은 확장프로그램으로 cookies를 내보냅니다 (JSON 또는 Netscape 형식);
파일을 저장소 폴더 밖에 저장합니다. 예:
C:\secrets\pyaterochka\cookies.json;경로를 지정합니다:
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.appcloudflared (무료 가능):
cloudflared tunnel --url http://localhost:8765
# получите адрес вида https://....trycloudflare.com클라이언트에 URL을 추가하세요:
클라이언트 | 추가하는 위치 |
Claude Desktop / Claude Web | Settings → Connectors → Custom connector → |
ChatGPT | Settings → Apps & Connectors → Create → URL |
Cursor | MCP settings → Add server → URL/SSE 타입 |
MCP Inspector |
|
⚠️ 보안 경고: 엔드포인트는 공개적이며 인증이 없습니다. 주소를 아는 사람은 누구 안 돼 도구를 사용할 수 있습니다. 지속적으로 사용하려면 리버스 프록시에서 기본 인증을 걸어주거나, 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 toolsfind_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
Scored across 12 tools
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.
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.
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.
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
Related MCP Connectors
Pay-per-use tool marketplace for AI agents. Search, price-check, and call APIs via MCP.
Hosted MCP for e-commerce: live product catalog, stock, and pricing for AI agents.
Agentic commerce with 58 MCP tools for product search, checkout, A2A negotiation, C-Suite analytics.
Geocoding, routing, isochrones, traffic, weather, and place search for AI agents. 19 MCP tools.
Related MCP Servers
- AlicenseAqualityDmaintenanceAn unofficial MCP server for interacting with Pyaterochka (5ka.ru) grocery store, enabling product search, cart management, and order delivery.244MIT
- FlicenseNot gradedqualityBmaintenanceProvides MCP tools to search products, check stock, and retrieve store information from the GTA7 Lab supermarket entity.-
- AlicenseBqualityCmaintenanceEnables LLM-driven interaction with the GLOBUS online store, including product search, catalog browsing, product details, promotions, recommendations, and anonymous shopping cart management via MCP.22MIT
- AlicenseAqualityCmaintenanceEnables AI agents to query tenants, browse catalogue items with pricing, pull recent orders, and add products through the MCP tool-calling interface.4MIT