Alko

You run Alko MCP Server to give AI assistants fast, structured access to the Alko product catalog, store data, and enrichment features like taste profiles, pairings, and Vivino ratings. This server combines product search, details, availability, store hours, recommendations, and region-specific queries in compact JSON for efficient use by language models.

How to use

You connect your MCP client to the Alko MCP Server and start querying against the Alko catalog. Typical workflows include: searching products by name, type, country, or price; retrieving enriched product details such as taste profiles and serving suggestions; checking store hours and real-time stock in stores; getting wine recommendations based on meals or occasions; and fetching Vivino ratings by wine name or URL. All results are returned as compact JSON to minimize token usage.

How to install

Follow these concrete steps to set up the Alko MCP Server locally for development and testing.

# Prerequisites
- Node.js 24+
- Google Cloud Firestore (or an emulator for local development)
- Playwright (auto-installed for web scraping)

# Clone the project
git clone https://github.com/yourusername/alko-mcp.git
cd alko-mcp

# Install dependencies
npm install

# Install Playwright browsers (Chromium)
npx playwright install chromium

# Build the server
npm run build

Local development with Firestore emulator

Run the Firestore emulator in the background, then start the MCP server. Use the emulator host for Firestore requests.

gcloud emulators firestore start --host-port=localhost:8081

# Start the MCP server (local runtime) with the emulator hostname set
MCP_TRANSPORT=http PORT=3000 node dist/server.js

Optional: Fresh data sync

If you need up-to-date product and store data, you can sync from the source Excel price list and the Alko store pages.

export FIRESTORE_EMULATOR_HOST=localhost:8081

# Sync fresh products from Excel (~30 seconds)
npm run sync-data

# Sync fresh stores from website (~2 minutes)
npm run sync-stores

# Export to seed file (for sharing with team)
npm run export-seed

Configuration for clients

Configure your MCP clients to connect to the server when running locally or in production. The server uses environment variables to control transport and port. In local development, you’ll typically start the server with node and provide the built dist/server.js path.

Example prompts and usage ideas

• Quick search: Find Italian red wines under 20 euros.
• Details: Get enriched data for a specific product by its ID.
• Availability: Check if a Barolo is in stock at Helsinki stores.
• Vivino: Retrieve Vivino ratings for a set of wines by name or URL.
• Recommendations: Get wine suggestions to pair with seafood or a cheese board.

Notes and troubleshooting

• Seed data loads on first query if the emulator has no data yet. Seed data is not persistent across emulator restarts.
• The emulator does not persist data between restarts; seed data will re-load automatically on first use.
• Web scraping for store availability relies on Playwright; ensure browsers are installed and network access is allowed.

Available tools

search_products

Search products by name, type, country, price range, alcohol % and other attributes.

get_product

Retrieve detailed product information. Include enriched data with includeEnrichedData=true to get taste profiles, food pairings, and serving tips.

get_store_hours

Retrieve store opening hours with optional filters for city, store name, or openNow=true. Data auto-refreshes if stale.

get_availability

Check real-time stock availability for a product in Alko stores (web scraping).

list_stores

List Alko stores by city.

get_recommendations

Get personalized product recommendations based on food pairings, occasions, and user preferences.

get_vivino_rating

Get Vivino wine rating by name or URL via scraping.

sync_products

Sync the product database with the latest Alko price list.

get_sync_status

Check synchronization status and current product count.