PrijsProfeet MCP

<h1 align="center">PrijsProfeet MCP</h1>

<p align="center">Unofficial MCP server for the PrijsProfeet API.</p>

<p align="center"> <a href="https://github.com/thijserven/prijsprofeet-mcp/actions/workflows/publish-container.yaml"><img src="https://github.com/thijserven/prijsprofeet-mcp/actions/workflows/publish-container.yaml/badge.svg" alt="Container publish workflow"></a> <a href="https://github.com/thijserven/prijsprofeet-mcp/blob/main/package.json"><img src="https://img.shields.io/badge/npm-v1.0.0-CB3837?logo=npm&logoColor=white" alt="npm package version 1.0.0"></a> <a href="https://www.typescriptlang.org/"><img src="https://img.shields.io/badge/TypeScript-5.9.3-3178C6?logo=typescript&logoColor=white" alt="TypeScript 5.9.3"></a> <a href="https://nodejs.org/"><img src="https://img.shields.io/badge/Node.js-%E2%89%A522-339933?logo=nodedotjs&logoColor=white" alt="Node.js 22 or newer"></a> <a href="https://modelcontextprotocol.io/"><img src="https://img.shields.io/badge/MCP-2.0.0-5A45FF" alt="Model Context Protocol SDK 2.0.0"></a> </p>

[!WARNING] This is an independent integration. It is not developed, endorsed, or supported by PrijsProfeet.

PrijsProfeet MCP exposes all 24 operations from the supported PrijsProfeet API contract as validated MCP tools. Use it from a local stdio client or deploy it as an authenticated Streamable HTTP server.

Contents

• Quick start: Docker + GHCR
• Manual build
• Development mode
• Connect an MCP client
• Capabilities
• Configuration
• Architecture
• Quality checks
• Operational notes

Quick start: Docker + GHCR

Prerequisites: Docker Engine with Docker Compose v2. The GitHub Actions workflow publishes ghcr.io/thijserven/prijsprofeet-mcp:latest on pushes to main and also publishes immutable sha-<commit> tags.

git clone https://github.com/thijserven/prijsprofeet-mcp.git
cd prijsprofeet-mcp

# Required: protect the remote MCP endpoint.
export PRIJSPROFEET_MCP_AUTH_TOKEN="$(openssl rand -base64 32)"
export PRIJSPROFEET_MCP_BIND_ADDRESS="127.0.0.1:3000"
export PRIJSPROFEET_MCP_IMAGE="ghcr.io/thijserven/prijsprofeet-mcp:latest"

# Optional: required for PrijsProfeet Pro endpoints.
export PRIJSPROFEET_API_KEY=""

docker compose up --detach
curl --fail http://127.0.0.1:3000/health

The server is now available at http://127.0.0.1:3000/mcp. Authenticate every MCP request with Authorization: Bearer <PRIJSPROFEET_MCP_AUTH_TOKEN>.

For a production deployment, replace :latest with a reviewed immutable digest (or an immutable sha-<commit> tag). Do not expose the endpoint directly to the public internet; bind to loopback or a specific LAN address and put an access-controlled reverse proxy in front of it when remote access is required.

To stop it:

docker compose down

Manual build

Use this path to build the image from the checked-out source rather than pulling GHCR.

git clone https://github.com/thijserven/prijsprofeet-mcp.git
cd prijsprofeet-mcp

export PRIJSPROFEET_MCP_AUTH_TOKEN="$(openssl rand -base64 32)"
export PRIJSPROFEET_MCP_BIND_ADDRESS="127.0.0.1:3000"
export PRIJSPROFEET_API_KEY="" # Optional; needed for Pro endpoints.

docker compose -f docker-compose.local.yaml up --build --detach
curl --fail http://127.0.0.1:3000/health

The local image is named prijsprofeet-mcp:local. Stop it with:

docker compose -f docker-compose.local.yaml down

Development mode

Prerequisites: Node.js 22+ and npm.

npm install
cp .env.example .env
npm run dev

npm run dev starts the stdio transport directly from TypeScript. stdout is reserved for the MCP protocol, so use an MCP client or the Inspector to interact with it. Add PRIJSPROFEET_API_KEY to .env only when you need Pro endpoints.

For the built stdio executable:

npm run build
node dist/index.js

Connect an MCP client

Streamable HTTP (Docker)

Configure an MCP client with:

URL:     http://127.0.0.1:3000/mcp
Header:  Authorization: Bearer <your PRIJSPROFEET_MCP_AUTH_TOKEN>

GET /health is public; /mcp always requires the bearer token.

stdio (local development or manual build)

Use the built entrypoint. The server reads .env from its current working directory, so set the client's working directory to the repository root or pass the environment explicitly.

{
  "mcpServers": {
    "prijsprofeet": {
      "command": "node",
      "args": ["/absolute/path/to/prijsprofeet-mcp/dist/index.js"],
      "cwd": "/absolute/path/to/prijsprofeet-mcp"
    }
  }
}

Capabilities

Every tool validates its input with Zod before an upstream request. Object responses are returned both as readable JSON text and as MCP structuredContent. Upstream HTTP errors and timeouts are returned as MCP tool errors.

Area	Tools
Health	health_check
Products	list_products, get_product, get_price_history, get_forecast, search_products_by_name, get_products_by_folder, get_products_by_retailer, get_promotional_products
Search	search_products, get_categories, get_filter_stats
Matching	match_by_ean, match_product, compare_prices, get_ean_stats
Deals	get_top_deals, get_brand_deals, get_deals_summary, get_popular_deals, get_deals_by_type, get_new_deals
Partner	request_free_api_key, get_partner_usage

API-key requirements

Public product, search, deal, and category operations can run without an API key. A PrijsProfeet Pro key is required for get_price_history, match_by_ean, match_product, compare_prices, and get_ean_stats. get_partner_usage also requires a key.

The MCP tool metadata includes _meta["nl.prijsprofeet/requiresProPlan"] so compatible clients can identify Pro-only tools before calling them. Request a free key through the PrijsProfeet API page or request_free_api_key.

Configuration

API client

Set these variables in .env for local stdio use, or in the deployment environment for Docker. Never commit .env.

Variable	Default	Purpose
PRIJSPROFEET_API_KEY	unset	Sent as X-API-Key; needed for Pro endpoints and usage
PRIJSPROFEET_BASE_URL	https://www.prijsprofeet.nl	API origin; non-HTTPS is allowed only for localhost
PRIJSPROFEET_TIMEOUT_MS	15000	Positive upstream request timeout in milliseconds
PRIJSPROFEET_USER_AGENT	project default	Identifies this integration to PrijsProfeet

HTTP server (Docker)

Variable	Required	Purpose
PRIJSPROFEET_MCP_AUTH_TOKEN	Yes	Bearer token required for /mcp
PRIJSPROFEET_MCP_BIND_ADDRESS	Yes	Host address and port, for example 127.0.0.1:3000
PRIJSPROFEET_MCP_IMAGE	GHCR compose file only	Image reference, for example ghcr.io/thijserven/prijsprofeet-mcp:latest
PRIJSPROFEET_MCP_HOST	No	Container bind host; defaults to 0.0.0.0
PRIJSPROFEET_MCP_PORT	No	Container port; defaults to 3000

Architecture

stdio: src/index.ts ──────────────┐
                                   ├─ src/server.ts ─ src/tools/definitions.ts ─ PrijsProfeet API
HTTP:  src/http-entry.ts ─ src/http.ts ┘                    │
                                                             └─ Zod input schemas

• src/tools/definitions.ts is the deterministic tool catalog: endpoint paths, HTTP methods, argument mapping, metadata, and validation.
• src/api/client.ts owns URL construction, headers, JSON encoding, timeouts, and upstream-error translation. src/config.ts is the only environment-reading boundary.
• src/server.ts is transport-independent. src/index.ts hosts stdio; src/http-entry.ts hosts authenticated Streamable HTTP.

dist/ is generated by npm run build; do not edit it directly.

Quality checks

npm run check
npm pack --dry-run

npm run check formats-checks, lints, type-checks, runs unit/in-memory MCP/stdio handshake tests, and builds the project. Tests do not call the live PrijsProfeet API.

For interactive local inspection:

npm run inspect

The Inspector launches the built stdio server. Tool calls made there are live upstream calls and count toward PrijsProfeet rate limits.

Operational notes

• Respect the PrijsProfeet API terms, upstream rate limits, and anti-bot controls. This server does not bypass those controls and does not automatically retry requests, including 429 responses.
• Pricing matches are not automatically current offers. Before presenting a cheapest current price, check is_current_deal, promotion_status, valid_from, and valid_until; use current_only: true where a matching tool supports it.
• EAN matching is exact when an EAN exists. Name/brand/category matching is indicative, not proof of product identity. Dietary labels are indicative and not allergen information.

References

• Model Context Protocol documentation
• PrijsProfeet API documentation
• PrijsProfeet API overview
• PrijsProfeet API terms