Skip to main content
Glama
deenkoru
dreamcatchered

Pyaterochka MCP Tool

by dreamcatchered
OverviewSchemaRelated ServersScoreDiscussions
Python
Hybrid

🛒 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: E-Commerce MCP Server

🏗️ 아키텍처

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

Install Server
A
license - permissive license
C
quality
C
maintenance

How are these scores calculated?

Maintenance

–Maintainers
–Response time
–Release cycle
–Releases (12mo)
Commit activity

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Tools

View all tools

Related MCP Servers

View all related MCP servers

Related MCP Connectors

  • mcp-knowledge

    100+ MCP tools for AI agents: content metadata, trade intelligence, business-expertise analysis.

  • pocket-agent-mcp

    Pocket Agent (aipocketagent.com) MCP server — read tools for personas, apps, and product info.

  • Presso

    Connect e-commerce and marketing data to AI assistants via MCP.

View all MCP Connectors

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/dreamcatchered/pyaterochka-mcp-tool'

If you have feedback or need assistance with the MCP directory API, please join our Discord server