Dutch Supermarkets MCP

TypeScript MCP server for Dutch supermarket and drugstore prices, promotions, shopping lists, meal planning, price alerts, routes, and budgets.

MCP tools

Tool	Purpose
search_products	Search supermarket and drugstore products
compare_prices	Compare the cheapest matching product per store
optimize_shopping_list	Split a list across the cheapest stores
list_supermarkets	List stores and product counts
list_drugstores	List drugstores and active promotion counts
list_promotions	Search current promotions by store/category
search_recipes	Search recipes by text, category, diet, or duration
plan_meals	Generate a meal plan and priced shopping list
get_price_history	Show recent price ranges
create_price_alert	Create a price or promotion alert
check_price_alerts	Check active alerts against current data
save_shopping_list	Save a shopping list
load_shopping_list	Re-price a saved list
list_shopping_lists	List saved shopping lists
get_purchase_advice	Recommend buying now or waiting
find_stores	Find nearby stored locations
plan_store_route	Group cheapest products into store stops
set_budget	Set the current weekly budget
check_budget	Price a list against a budget
get_saving_tips	Find promotion savings

Tool names, input fields, descriptions, and responses are English. Dutch terms are retained only in synchronized source values and matching keywords required by Dutch retailer data sources.

Docker quick start

cp .env.example .env
# Replace DB_PASSWORD and HTTP_AUTH_TOKEN with random values.
docker compose up -d --build

The stack contains:

• db: PostgreSQL 16 with docker/init.sql
• mcp-server: authenticated Streamable HTTP at http://localhost:8000/mcp
• scheduler: initial sync followed by 12-hour product/promotion/recipe syncs

The MCP and scheduler initialize the PostgreSQL schema themselves from the schema bundled in the image. A deployment consuming the published image does not need to clone this repository or mount docker/init.sql.

GitHub Container Registry deployment

Every push to main publishes two image tags through .github/workflows/publish-container.yml:

ghcr.io/thijserven/dutch-supermarkets-mcp:latest
ghcr.io/thijserven/dutch-supermarkets-mcp:<full-commit-sha>

services:
  dutch-supermarkets-db:
    image: postgres:16-alpine
    restart: unless-stopped
    environment:
      POSTGRES_DB: dutch_supermarkets
      POSTGRES_USER: postgres
      POSTGRES_PASSWORD: ${DUTCH_SUPERMARKETS_DB_PASSWORD}
    volumes:
      - dutch-supermarkets-data:/var/lib/postgresql/data
    healthcheck:
      test: ['CMD-SHELL', 'pg_isready -U postgres -d dutch_supermarkets']
      interval: 5s
      timeout: 5s
      retries: 10

  dutch-supermarkets-mcp:
    image: ghcr.io/thijserven/dutch-supermarkets-mcp:<full-commit-sha>
    restart: unless-stopped
    depends_on:
      dutch-supermarkets-db:
        condition: service_healthy
    environment: &dutch-supermarkets-env
      DB_HOST: dutch-supermarkets-db
      DB_PORT: 5432
      DB_NAME: dutch_supermarkets
      DB_USER: postgres
      DB_PASSWORD: ${DUTCH_SUPERMARKETS_DB_PASSWORD}
      ENABLE_HTTP_SERVER: 'true'
      HTTP_HOST: '0.0.0.0'
      HTTP_PORT: 8000
      HTTP_AUTH_TOKEN: ${DUTCH_SUPERMARKETS_MCP_AUTH_TOKEN}

  dutch-supermarkets-scheduler:
    image: ghcr.io/thijserven/dutch-supermarkets-mcp:<full-commit-sha>
    restart: unless-stopped
    depends_on:
      dutch-supermarkets-mcp:
        condition: service_healthy
    environment:
      <<: *dutch-supermarkets-env
      SYNC_INTERVAL_MS: 43200000
    command: ['bin/scheduler.js']
    healthcheck:
      disable: true

volumes:
  dutch-supermarkets-data:

Check health:

curl http://localhost:8000/health

Connect an MCP client using either header:

Authorization: Bearer <HTTP_AUTH_TOKEN>
x-mcp-token: <HTTP_AUTH_TOKEN>

Example Hermes MCP configuration:

mcp_servers:
  dutch_supermarkets:
    url: http://mcp-server:8000/mcp
    headers:
      Authorization: Bearer ${HTTP_AUTH_TOKEN}

Local stdio setup

Requirements: Node.js 20+ and a reachable PostgreSQL database initialized with docker/init.sql.

npm ci
npm run build
DB_HOST=127.0.0.1 DB_PORT=5432 DB_PASSWORD=... node bin/mcp-server.js

ENABLE_HTTP_SERVER defaults to false, so the CLI uses stdio. An MCP client configuration can invoke it directly:

{
  "mcpServers": {
    "dutch-supermarkets": {
      "command": "node",
      "args": ["/absolute/path/to/dutch-supermarkets-mcp/bin/mcp-server.js"],
      "env": {
        "DB_HOST": "127.0.0.1",
        "DB_PORT": "5432",
        "DB_NAME": "dutch_supermarkets",
        "DB_USER": "postgres",
        "DB_PASSWORD": "..."
      }
    }
  }
}

Configuration

Variable	Default	Description
DB_HOST	127.0.0.1	PostgreSQL host
DB_PORT	5432	PostgreSQL port
DB_NAME	dutch_supermarkets	Database name
DB_USER	postgres	Database user
DB_PASSWORD	empty	Database password
ENABLE_HTTP_SERVER	false	Use Streamable HTTP instead of stdio
HTTP_HOST	0.0.0.0	HTTP bind host
HTTP_PORT	8000	HTTP bind port
HTTP_AUTH_TOKEN	unset	Optional HTTP bearer/custom-header token
HTTP_AUTH_HEADER_NAME	x-mcp-token	Custom token header

For exposed or shared HTTP deployments, always set HTTP_AUTH_TOKEN and place the server behind TLS. The Docker Compose stack requires the token.

Data synchronization

npm run sync -- prices
npm run sync -- promotions
npm run sync -- recipes
npm run sync -- all

Sources:

• Product prices: checkjebon.nl/data/supermarkets.json
• Promotions: public Folderz category pages
• Recipes: bundled Dutch recipes plus TheMealDB

These are third-party sources and can change or rate-limit requests. The sync commands fail visibly on source/database errors; existing database data remains available to the MCP server.

Development

npm test
npm run lint
npm run typecheck
npm run build

The test suite covers tool parity, Zod validation, parameterized SQL behavior, transport authentication, MCP protocol calls, geographic calculations, and promotion parsing.

License

MIT