Skip to main content
Glama
Gurkerl Recommender MCP

Gurkerl Recommender MCP

by Fernise

Gurkerl Recommender MCP

Nutrition- and budget-aware grocery ranking, offer monitoring and weekly digests, with offline samples and optional MCP/Telegram integrations.

CI

Technology: Python · SQLite · MCP · Optional Node.js bridge · Telegram

Overview · Quick start · Architecture · Verification

What it does

For developers and grocery shoppers experimenting with explainable recommendations and configurable weekly digests.

  • Explainable scoring for nutrition, price, promotions and close-to-expiry offers.

  • A dependency-free sample recommender and configurable monitoring pipeline.

  • Weekly plans/digests, notification deduplication and SQLite state.

  • An optional local MCP server and clients for authenticated external MCP services.

Related MCP server: Willys MCP Server

Offline example

Actual output from the bundled grocery-ranking sample

Captured from the bundled offline sample. Products and prices are illustrative; each recommendation exposes its scoring reasons.

Project status

A personal recommendation toolkit with reproducible offline examples. External service ingestion and account tools require separate credentials and authorization. Recommendations do not provide medical nutrition advice or automatically place orders.

Quick start

Requires Python 3.11+ for the documented setup; Node.js 22+ is needed only for the optional JavaScript bridge.

git clone https://github.com/Fernise/gurkerl-recommender-mcp.git
cd gurkerl-recommender-mcp
python3 -m venv .venv
. .venv/bin/activate
python -m pip install -e .
python -m gurkerl_recommender.cli --sample
python -m gurkerl_recommender.monitor_cli --config config.example.json

The sample configuration is offline and prints to the console. To expose the local recommendation tools through MCP:

python -m pip install -e '.[mcp]'
python -m gurkerl_recommender.server

For the optional Node SDK helper, run npm ci first. See configuration, scoring and MCP integration notes. Real account credentials belong only in an ignored local .env file.

Verification

python -m unittest discover -s tests -v

The suite uses sample products and mocked external responses. Authenticated grocery access, MCP account tools and Telegram delivery are not exercised during CI.

Repository map

Path

Responsibility

gurkerl_recommender/

Scoring, models, sources, MCP clients and CLI commands

tests/

Offline scoring, monitor, client and notifier regressions

scripts/

Optional Node MCP discovery helpers

config*.example.json

Safe source/notifier configuration examples

profile.example.json

Fictional recommendation preferences

deploy/

Example service/timer units

Documentation

License

Original project code is licensed under the MIT License.

Third-party libraries and assets retain their own licenses.

Tool Schema Changelog

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

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      A
      quality
      B
      maintenance
      A Model Context Protocol server for real-time Swiss grocery shopping that searches and compares products across 8 major Swiss retailers (Migros, Coop, Aldi, Denner, Lidl, Farmy, Volgshop, Otto’s), normalizes per-unit prices, surfaces promotions, computes optimal multi-store shopping plans, and works with any MCP-compatible client without API keys or accounts.
      7
      255 npm
      44
      -
    • A
      license
      A
      quality
      B
      maintenance
      A local MCP server for grocery shopping, enabling product search, specials, and browsing across NZ supermarkets, with cart and order history for Countdown/Woolworths via browser-assisted login.
      14
      1
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables users to search grocery products and stores, manage a cart, sync purchase history, and predict needed items through MCP tools. It also stores food preferences as server instructions so connected agents can respect them automatically.
      1
      MIT