Systembolaget API MCP Server

MCP server that exposes the Systembolaget (Swedish liquor store) product search API as a tool. Uses FastMCP and supports configurable launch date range and optional query parameters.

Setup

Clone or open this project.

Create a virtual environment and install dependencies:

   python3 -m venv .venv
   source .venv/bin/activate   # On Windows: .venv\Scripts\activate
   pip install -r requirements.txt

Set your API key. The API requires the Ocp-Apim-Subscription-Key header. Provide it via environment variable:

   export SYSTEMBOLAGET_SUBSCRIPTION_KEY=your-subscription-key-here

Copy .env.example to .env and fill in the key if you use a tool that loads .env (do not commit .env).

Running the server

From the project root (with the venv activated):

python server.py

Or using the FastMCP CLI:

fastmcp run server.py:mcp

The server runs over stdio by default (for use with Claude Desktop, Cursor, etc.).

You can also run it with uv (same pattern as other local MCP servers):

uv run --directory /path/to/bolki-mcp python server.py

Cursor MCP configuration

Add this server to Cursor’s MCP settings (e.g. Cursor Settings → MCP or ~/.cursor/mcp.json) using stdio and uv, in the same way as other local MCP servers:

{
  "mcpServers": {
    "systembolaget": {
      "type": "stdio",
      "command": "/opt/homebrew/bin/uv",
      "args": [
        "run",
        "--directory",
        "/Users/erik/Development/_dev/bolki-mcp",
        "python",
        "server.py"
      ],
      "env": {
        "SYSTEMBOLAGET_SUBSCRIPTION_KEY": "your-subscription-key-here"
      }
    }
  }
}

Use your actual project path for --directory (e.g. /Users/erik/Development/_dev/bolki-mcp).
Use your system’s uv path if different (e.g. uv if it’s on your PATH).
Set SYSTEMBOLAGET_SUBSCRIPTION_KEY to your API key. Do not commit the key; use a local config or secret.

Tool: `search_products`

Fetches all pages automatically and returns the combined result.

Parameters:
launch_date_min (required) – Start of launch date range, YYYY-MM-DD. Maps to productLaunch.min.
launch_date_max (required) – End of launch date range, YYYY-MM-DD. Maps to productLaunch.max.
size (optional, default 100) – Page size used when fetching; all pages are requested automatically.
sort_by (optional, default "Score") – Sort field.
sort_direction (optional, default "Ascending") – Sort direction.
assortment_text (optional, default "Tillfälligt sortiment") – Assortment filter.
full_response (optional, default False) – If False, returns a compact response for speed; if True, returns the full API-style JSON.

Returns: By default a compact response: metadata (docCount, totalPages, nextPage, previousPage) and products with key fields only (productId, productNameBold, productNameThin, producerName, price, volume, volumeText, alcoholPercentage, country, categoryLevel1, customCategoryTitle, assortmentText, productLaunchDate, taste, usage, vintage). Set full_response=True to get the full response (all fields, filters, etc.) when needed.

Tool: `list_products_formatted`

Returns a ready-to-use list of lines (filtering and formatting done in the MCP; no client-side parsing). Fetches all pages automatically so the list is complete.

Parameters: Same launch_date_min, launch_date_max as above, plus:
product_filter: "beer" (default) – only products with CategoryLevel1 "Öl"; "all" – every product.
size – page size used when fetching (default 100); all pages are requested automatically.
sort_by, sort_direction, assortment_text – same as search_products.
Returns: Sorted unique list of strings, e.g. ["Vreta klosters Våröl — 330 ml, 5.6%", ...]. Use this instead of running Python scripts to parse search results.

License

Use of the Systembolaget API is subject to Systembolaget’s terms. This project is for integration only.

Systembolaget API MCP Server