Skip to main content

serbia-prices-mcp

An MCP server for grocery prices in Serbia. It downloads the daily price lists that retail chains publish on data.gov.rs, stores them in a local DuckDB file and lets an AI assistant search, compare and price a shopping list across chains.

Chains: Lidl, Maxi (also Mega Maxi, Shop&Go), Idea (also Mercator, Roda), Univerexport, Gomex, Aman, Metro, dm, Aroma, Svetofor and Veropoulos — the major chains in Belgrade and Novi Sad.

It runs on your computer. There is no account, API key or hosted service.

Why

The chains publish their prices as open data, but in a form that is hard to use directly: one CSV per chain, each with its own column names, unit spellings and encoding problems. The portal has no search and no way to compare chains. This server normalizes the files into one table so the assistant can answer questions like:

  • Where is this product cheapest, and by how much?
  • Which store is cheapest for my shopping list?
  • Is this discount real, or was the regular price raised before it?
  • How has the price changed over the last months?

Example questions

You can ask in any language. The assistant translates product names to Serbian before calling the tools.

  • "Price a weekly basket for two in every store: 2 l of milk, bread, 10 eggs, chicken breast, cheese, bananas, coffee. Which store is cheapest and how much do I save compared to the most expensive one?"
  • "I'm cooking carbonara for six. Price the ingredients in Maxi, Lidl and Idea."
  • "Show the 10 biggest discounts on meat and say which ones look inflated."
  • "Which Lidl and Maxi promotions end tomorrow?"
  • "Where is Coca-Cola 2 l cheapest, and is the two-pack promotion a better deal?"
  • "Find Lurpak butter 250 g and compare that exact product across all chains."
  • "How has the price of 2.8% milk changed since September in Maxi and Idea?"

Install

You need uv. The server uses the stdio transport, so it works in clients that start local MCP servers: Claude Code, Claude Desktop, Codex, Antigravity, Cursor, VS Code. It does not work in web-only clients such as ChatGPT or claude.ai in the browser.

Claude Code

claude mcp add --scope user serbia-prices -- uvx serbia-prices-mcp

Codex

codex mcp add serbia-prices -- uvx serbia-prices-mcp

or in ~/.codex/config.toml:

[mcp_servers.serbia-prices]
command = "uvx"
args = ["serbia-prices-mcp"]

Antigravity

agy mcp add serbia-prices uvx serbia-prices-mcp

Claude Desktop (claude_desktop_config.json), Cursor (~/.cursor/mcp.json)

{ "mcpServers": { "serbia-prices": { "command": "uvx", "args": ["serbia-prices-mcp"] } } }

VS Code (.vscode/mcp.json)

{ "servers": { "serbia-prices": { "type": "stdio", "command": "uvx", "args": ["serbia-prices-mcp"] } } }

On the first start the server downloads about 135 MB of price lists and builds the database, which takes about half a minute. Until then the tools return "retry in a minute". To download in advance:

uvx serbia-prices-mcp sync

Tools

Tool Description
search_products Search by name: most relevant names first, then the cheapest package. With ean: one exact product in all chains and store formats, with the difference from the cheapest in RSD and %.
optimize_basket Cost of a shopping list in each store. Items are given by name or by barcode, quantity in packages. Stores that have every item come first.
get_top_discounts Current promotions. Flags a regular price that is higher than in recent monthly snapshots, and discounts of 80% or more, which are usually clearance or data errors.
get_price_history Monthly snapshots published by the chains plus today's price for one barcode.
list_retailers_and_categories Chains, store formats, date of the data and the 25 product categories.

All tools are read-only. Lists are paged with limit and offset and return total.

How it works

  1. For each chain the server asks the data.gov.rs API for the chain's datasets and takes the newest price list CSV.
  2. It downloads all files in parallel.
  3. One parser reads every file: it maps the column names to one schema, unifies units (kom, kom., KOM), validates prices and dates, skips invalid rows and prepares text for search without diacritics.
  4. The rows are loaded into a new DuckDB file, which then replaces the old one. If a chain fails to download or parse, its previous prices are kept.
  5. Each tool call is one SQL query over the file, opened read-only. Queries take 30–100 ms.
  6. While running, the server checks every hour and downloads again when the data is older than 20 hours.

No history is collected. The chains' files contain today's prices and monthly snapshots for recent months; price history and the discount check use those snapshots. The database takes about 50 MB in ~/.cache/serbia-prices-mcp.

Settings

Variable Default Description
SERBIA_PRICES_MCP_DATA_DIR ~/.cache/serbia-prices-mcp Directory for prices.duckdb
SERBIA_PRICES_MCP_TRANSPORT stdio http serves Streamable HTTP at /mcp
SERBIA_PRICES_MCP_HOST, SERBIA_PRICES_MCP_PORT 127.0.0.1, 8000 HTTP address
SERBIA_PRICES_MCP_LOG_LEVEL INFO Log level; logs go to stderr

Data

The price lists are published by the retail chains on data.gov.rs under the Open Data License of the Republic of Serbia. Prices are shown as published and may differ in the store. This project is not affiliated with the chains or the portal.

Development

uv sync
uv run pytest
uv run mypy src tests

License

MIT

Metadata

Release files for serbia-prices-mcp 0.1.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for serbia-prices-mcp 0.1.1
File Size Uploaded Provenance Actions
serbia_prices_mcp-0.1.1.tar.gz 117.5 kB Without provenance Details for serbia_prices_mcp-0.1.1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for serbia-prices-mcp 0.1.1
File Interpreter ABI Platform Actions
serbia_prices_mcp-0.1.1-py3-none-any.whl Python 3 none any Details for serbia_prices_mcp-0.1.1-py3-none-any.whl

Total release size: 138.1 kB

Release files / serbia_prices_mcp-0.1.1.tar.gz

Download URL serbia_prices_mcp-0.1.1.tar.gz
Size 117.5 kB
Tags Source
SHA-256 checksum
How to use checksums
fe1d22842d72f5e0cc7ab9e6a3eaf8477906b2893424cff83cef925fed1706d9
BLAKE2b-256 checksum
How to use checksums
e367b501ea01c95a37021dff4f437b16d92947c062a3b002dfeac79075a05909
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via uv/0.13.8 {"installer":{"name":"uv","version":"0.13.8","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"26.04","id":"resolute","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

Release files / serbia_prices_mcp-0.1.1-py3-none-any.whl

Download URL serbia_prices_mcp-0.1.1-py3-none-any.whl
Size 20.6 kB
Tags Python 3
SHA-256 checksum
How to use checksums
4590096b930ec37b3901751ca95e36894e095eea45d97bb97a198070609bd8ae
BLAKE2b-256 checksum
How to use checksums
c77aee362e8ea2fb3e67c1c6a39a05b5a18b25f470fd1d21c1ddf8abadd7dc49
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via uv/0.13.8 {"installer":{"name":"uv","version":"0.13.8","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"26.04","id":"resolute","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

Security for serbia-prices-mcp 0.1.1

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page