Recipe Shopping List — MCP Server

MCP server (Model Context Protocol) that can:

1. Read recipes from food.ru — extracts ingredients, steps, and nutritional info from a link

2. Search products on magnit.ru — for a specific store

3. Compile a shopping list — finds products with prices for a recipe and calculates the total

4. Show store information — by store code

Result: you provide a recipe link — you get a ready shopping list with prices from Magnit and direct product links.

🎓 Educational project: the project was used to teach category managers at a retail chain how to build MCP servers. It's a hands-on case with a full cycle: from idea and technical specification to a working MCP server used by an AI assistant. Participants build a working application with an AI agent — a recipe parser from food.ru, product search on magnit.ru, and a priced shopping list — and get a tangible result in a single session.

🌐 Web version: in addition to the MCP interface, there's a local web interface — it doesn't require an MCP client and works in the browser. Launch with a single command:

./start.sh   # запустить и открыть страницу в браузере (http://127.0.0.1:8000)
./stop.sh    # остановить сервер

In the web version, you can paste a recipe link, get a shopping list table, and save it to Excel. Details in the “Web Interface” section.

Installation

Quick method: the install.py installer

The install.py script (uses only the Python standard library — nothing extra to install) does everything itself: creates a virtual environment, installs dependencies and the Playwright browser, creates .env, registers the server with the selected MCP clients, and verifies everything works.

Requires Python 3.11+ (we recommend uv — the installer will find both uv and regular Python).

python install.py      # или: python3 install.py

All flags are optional:

Examples:

python install.py --check              # проверка окружения без изменений
python install.py --yes                # установка «на все по умолчанию»
python install.py --shop-code 992301 --clients opencode,claude

Manual installation

Requires Python 3.11+ (we recommend uv).

# 1. Виртуальное окружение и зависимости
uv venv --python 3.11 .venv
uv pip install --python .venv/bin/python -r requirements.txt

# 2. Браузер для Playwright (оба сайта — SPA, без браузера никак)
.venv/bin/python -m playwright install chromium

# 3. Секреты
cp .env.example .env   # при необходимости поправь код магазина по умолчанию

Related MCP server: Recipe Commerce Intelligence MCP

Running

.venv/bin/python src/server.py

The server works via the MCP protocol over stdio — it's invoked by an AI assistant (Claude Desktop, LM Studio, etc.); on its own it "stays silent" in the terminal.

Web Interface

A local web page for those who don't want to set up an MCP client: paste a recipe link — get a shopping list table with a save-to-Excel button.

Launch (the server will open the page in the browser itself):

./start.sh     # запустить и открыть браузер
./stop.sh      # остановить сервер

Running ./start.sh again while the server is already running simply opens the page. Manually (if the scripts don't work):

.venv/bin/python src/web/server.py

Open in your browser: http://127.0.0.1:8000

What the page can do:

• paste a food.ru recipe link and click the button — the server will compile a shopping list (requests to the sites take 30–90 seconds, a progress indicator is shown);

• display a table: ingredient, quantity, product at Magnit, price, quantity to buy, total, product link;

• save the list to an Excel file with the "Save to Excel" button.

Excel files are saved to the exports/ folder in the project root (filename format: shopping_list_<recipe>_<date>.xlsx).

Connecting to OpenCode

In ~/.config/opencode/opencode.jsonc (globally) or opencode.json in the project root, add an mcp section — the format differs from Claude Desktop (the command key is an array, variables are in environment):

{
  "mcp": {
    "recipe-shopping-list": {
      "type": "local",
      "command": [
        "/ПОЛНЫЙ/ПУТЬ/К/MCP_rec/.venv/bin/python",
        "/ПОЛНЫЙ/ПУТЬ/К/MCP_rec/src/server.py"
      ],
      "environment": {
        "MAGNIT_SHOP_CODE": "543440",
        "MAGNIT_SHOP_TYPE": "dostavka",
        "LOG_LEVEL": "INFO"
      },
      "enabled": true
    }
  }
}

After restarting OpenCode, the server will appear in the MCP list (the /mcp command in the app). To verify from the terminal (opencode mcp list) — note that in the installed version via OpenCode.app this won't work, since the CLI is an Electron wrapper.

Connecting to Claude Desktop

In claude_desktop_config.json, add (paths must be absolute):

{
  "mcpServers": {
    "recipe-shopping-list": {
      "command": "/ПОЛНЫЙ/ПУТЬ/К/MCP_rec/.venv/bin/python",
      "args": ["/ПОЛНЫЙ/ПУТЬ/К/MCP_rec/src/server.py"],
      "env": {
        "MAGNIT_SHOP_CODE": "543440",
        "MAGNIT_SHOP_TYPE": "dostavka",
        "LOG_LEVEL": "INFO"
      }
    }
  }
}

Tools

Example

“Here's a recipe: https://food.ru/recipes/269806-sous-iz-iogurta-s-ukropom-i-chesnokom-1766588076”

The agent will call get_shopping_list and return:

Греческий йогурт — 100г → Йогурт греческий Teos 2% 140г — 89,90 ₽ [ссылка]
Чеснок — 2 зубчик =10г → Чеснок свежий 100г — 45,00 ₽ [ссылка]
...
Итого: 356,70 ₽ · 6 товаров

Tests

Quick logic tests (don't hit the sites — parsers are replaced with mocks):

.venv/bin/python -m pytest tests/ -v

Live integration tests — actually open food.ru and magnit.ru via Playwright, like the real server (~1 minute, with pauses between requests):

.venv/bin/python -m pytest -m integration -v

Live test rules: if the site is unavailable (network) — the test is skipped; if the site responds but the structure is different — the test fails (the markup has changed, time to update the selectors and record the lesson in LESSONS.md).

Structure

src/
├── server.py                  # Точка входа MCP-сервера
├── tools/                     # MCP-инструменты (бизнес-логика)
├── integrations/              # Парсеры сайтов (Playwright)
├── models/                    # Pydantic-модели
├── utils/                     # Кэш, ограничитель запросов, валидаторы
└── config/                    # Настройки (.env) и селекторы

Important to know

• Both sites (food.ru, magnit.ru) are SPAs: data is loaded via JavaScript. Therefore, the parsers work through Playwright (headless browser) rather than plain HTTP.

• There's a 2–5 second pause between requests to the sites, and results are cached (recipes for 24 hours, products for 15 minutes).