NL Supermarkt

You have access to a Model Context Protocol (MCP) server that aggregates Dutch supermarket and drugstore pricing data, helps you compare prices, plan shopping lists, and track your budget. It connects with multiple sources to give you up-to-date products, promotions, recipes, and weeklong meal planning, all in one place.

How to use

Use an MCP client to connect to the nl_supermarkt MCP server and access features like product search, price comparisons, shopping list optimization, promotions, recipe discovery, and weekly menu planning. You can also enable price history and alerts, save and load shopping lists, plan routes to nearby stores, track a budget, and view drugstore promotions. Exercise patterns you’ll use often include creating a shopping plan for a week, setting a price alert for a favorite item, and loading saved lists with current prices and offers.

How to install

Prerequisites you need before starting are Python (for data sync utilities) and Docker or Docker Compose for running services in containers. You should also have Node.js/npm if you plan to run MCP client helpers locally.

Step-by-step setup and run flow based on common MCP server patterns from the source content:

# Clone the project repository
git clone https://github.com/Samvox1/nl-supermarkt-mcp.git
cd nl-supermarkt-mcp

# Start the server stack with Docker Compose
docker compose up -d

# First data synchronization (takes about 5 minutes)
docker compose run --rm scheduler python3 sync_folderz.py

Configuration and ongoing operations

You can configure how the MCP client connects to the server. One ready-to-use local client setup uses a JSON configuration that points the client to the MCP endpoint exposed by the local server.

{
  mcpServers: {
    nl-supermarkt: {
      command: npx,
      args: [-y, mcp-remote, http://localhost:8000/sse, --allow-http]
    }
  }
}

Notes and additional capabilities

Data sources include price data from checkjebon.nl (daily at 07:00), promotions from Folderz.nl (twice daily for stores and drugstores), and recipes from TheMealDB plus NL custom recipes. Automatic sync tasks keep prices, promotions, and recipes up to date.

Environment and development notes

You may need environment variables for the database and runtime. The following are the typical variables you’ll encounter when running the MCP server stack locally.

Examples of actions you can perform

Week planning with budget, checking drugstore promotions, setting price alerts, and budgeting checks are all supported through the MCP interface or client integrations.

Troubleshooting tips

If data syncing stalls or a connection to the local MCP endpoint cannot be established, verify that Docker services are running, the scheduler is able to reach its data sources, and the http endpoint (for MCP) is accessible from your client.

Security considerations

Only expose MCP endpoints to trusted clients. Use the --allow-http flag with caution in development and prefer secured connections in production. If you expose a local endpoint, ensure proper network controls and authentication where supported.

Tools and capabilities overview

The server provides tools for price history, price alerts, smart shopping lists, store routing, budget tracking, and drugstore promotions. These tools enable you to track price trends, save and reuse shopping lists, check if you’re within budget, and view promotions by category.

Quick start for Claude Desktop users

To connect Claude Desktop to the local MCP server, add this configuration to your Claude desktop config.

{
  mcpServers: {
    nl-supermarkt: {
      command: npx,
      args: [-y, mcp-remote, http://localhost:8000/sse, --allow-http]
    }
  }
}

Available tools

search_products

Search products across multiple Dutch supermarkets and drugstores.

compare_prices

Compare prices of products between different stores.

optimize_shopping_list

Find the cheapest combination to meet your shopping needs.

view_offers

View current folder and drugstore offers with various promo types.

search_recipes

Search recipes with dietary filters (vegetarian, vegan, gluten-free).

plan_week_menu

Plan meals for the week with an automatic shopping list.

price_history

View price history and trends for products.

price_alert

Set alerts for products below a target price.

check_alerts

Check which alerts currently represent good deals.

save_shopping_list

Save shopping lists for reuse.

load_shopping_list

Load a list with current prices and offers.

list_shopping_lists

Overview of stored shopping lists.

find_stores

Find the nearest supermarkets.

plan_store_route

Plan an efficient route across multiple stores.

set_budget

Set a weekly budget for groceries.

budget_check

Check whether your shopping stays within budget.

spend_tips

Provide personalized saving tips.

list_pharmacies

Show all drugstores with offers.

view_pharmacy_offers

View offers by category (hair care, makeup, fragrance, etc.).