iiko-server-mcp

iikoServer MCP Server

MCP (Model Context Protocol) server exposing the iiko restaurant management system REST API as 42+ LLM-callable tools over stdio.

Features

• 42+ tools — products, employees, orders, payments, OLAP reports, assembly charts
• Auto-auth — SHA1 password hashing + session cookie, re-authenticates on 401
• Graceful shutdown — sends logout to release iiko license slot
• Self-signed cert support — IIKO_VERIFY_SSL=false by default
• Venue mapping — optional IIKO_VENUE_MAP to tag cash register numbers with names
• Business-level helpers — get_checks, get_venues_revenue, get_staff_meals, get_top_dishes, compare_revenue
• Docker-ready — Python 3.12-slim, stdio protocol

Quick Start

Local (pip)

git clone https://github.com/your-org/iiko-server-mcp.git
cd iiko-server-mcp
pip install -r requirements.txt

IIKO_URL=https://your-restaurant.iiko.it:443 \
IIKO_LOGIN=your_login \
IIKO_PASS=your_password \
python3 server.py

Docker

docker build -t iiko-server-mcp .
docker run -i --rm \
  -e IIKO_URL=https://your-restaurant.iiko.it:443 \
  -e IIKO_LOGIN=your_login \
  -e IIKO_PASS=your_password \
  iiko-server-mcp

Important: MCP servers use stdio (not HTTP). The container must run with -i (interactive) so the MCP client can communicate via stdin/stdout. Do not use -d (detached).

Configuration

Copy .env.example to .env and fill in real values:

Variable	Required	Default	Description
IIKO_URL	yes	—	iikoServer base URL, e.g. https://my-restaurant.iiko.it:443
IIKO_LOGIN	yes	—	Login username
IIKO_PASS	yes	—	Plain password (SHA1-hashed before sending)
IIKO_VENUE_MAP	no	—	"Venue A=4,Venue B=5" — names for cash register numbers
IIKO_VERIFY_SSL	no	false	Set to true if using a CA-signed certificate

MCP Client Configuration

Hermes Agent

# ~/.hermes/config.yaml
mcp_servers:
  iiko-server:
    command: python3
    args: ["/path/to/iiko-server-mcp/server.py"]
    env:
      IIKO_URL: "https://your-restaurant.iiko.it:443"
      IIKO_LOGIN: "your_login"
      IIKO_PASS: "your_password"
      IIKO_VENUE_MAP: "Cafe A=4,Cafe B=5"

For Docker:

mcp_servers:
  iiko-server:
    command: docker
    args: ["run", "-i", "--rm",
           "-e", "IIKO_URL=https://your-restaurant.iiko.it:443",
           "-e", "IIKO_LOGIN=your_login",
           "-e", "IIKO_PASS=your_password",
           "iiko-server-mcp"]

Claude Desktop

{
  "mcpServers": {
    "iiko-server": {
      "command": "python3",
      "args": ["/path/to/iiko-server-mcp/server.py"],
      "env": {
        "IIKO_URL": "https://your-restaurant.iiko.it:443",
        "IIKO_LOGIN": "your_login",
        "IIKO_PASS": "your_password"
      }
    }
  }
}

Cursor

{
  "mcpServers": {
    "iiko-server": {
      "command": "python3",
      "args": ["/path/to/iiko-server-mcp/server.py"],
      "env": {
        "IIKO_URL": "https://your-restaurant.iiko.it:443",
        "IIKO_LOGIN": "your_login",
        "IIKO_PASS": "your_password"
      }
    }
  }
}

Available Tools

System

• ping — Health check, server URL + auth state
• list_endpoints — All 42 tools with descriptions

Products / Nomenclature

• get_products / get_nomenclature — All products
• get_product_groups — Product categories with hierarchy
• get_product_sizes — Sizes/units
• get_corporate_structure — Departments structure
• get_corporate_groups — Corporate groups
• search_products — Substring search by name

Employees

• get_employees / get_employee / get_employee_roles / get_persons

Entities

• get_entity_types / get_entities / get_entity_by_id
• get_stores — Warehouses
• get_contractors — Suppliers

Documents

• get_incoming_invoices / get_outgoing_invoices — by date range (DD.MM.YYYY)
• get_incoming_invoice_by_id / get_outgoing_invoice_by_id
• get_waste_documents — Write-off documents
• get_menu_changes / get_menu_change_by_id

Recipes (Assembly Charts)

• get_assembly_charts — All tech cards
• get_assembly_chart_by_id — Single chart
• save_assembly_chart — Create/update (⚠️ modifies production data)

Cash & Payments

• get_payment_types
• get_cash_shifts / get_cash_shift — by session UUID
• get_payments / get_payment — per session
• create_encashment — Cash in/out (⚠️ modifies production data)

Prices

• get_price_categories / get_price_category

Reports & OLAP

• get_olap_columns — Schema for a report type (e.g. SALES)
• run_olap_report — Raw OLAP with custom columns/filters (DD.MM.YYYY)
• get_olap_presets / run_olap_by_preset — Saved presets
• run_custom_report — Named custom reports (DD.MM.YYYY)
• get_venues_revenue — Daily revenue by venue (YYYY-MM-DD)
• get_staff_meals — Free staff meals per venue (YYYY-MM-DD)
• get_top_dishes — Top N dishes by revenue (YYYY-MM-DD)
• compare_revenue — Day-over-day revenue comparison
• get_checks — Individual orders with payment type & masked card (YYYY-MM-DD)

Raw

• raw_request — Direct authenticated HTTP call to any iikoServer endpoint

Date Format

Tool Group	Format	Example
Business helpers (get_venues_revenue, get_checks, etc.)	YYYY-MM-DD	2026-07-17
Legacy OLAP (run_olap_report, run_olap_by_preset)	DD.MM.YYYY	17.07.2026

All business tools default to Moscow time (UTC+3) if no date is provided.

Known Limitations

• get_cash_shifts — requires a date parameter; currently returns 409 if called without one
• get_payment_types — returns 404 on some iikoServer versions (endpoint may not exist)
• Staff meal detection — filters by "(без оплаты)" payment type label; verify this matches your iiko configuration
• CardTypeName — may return "(нет карты)" depending on acquirer integration
• Self-signed certs — default verify=False; set IIKO_VERIFY_SSL=true for CA-signed certificates

Development

# Syntax check
python3 -m py_compile server.py

# Run locally with test env
IIKO_URL=... IIKO_LOGIN=... IIKO_PASS=... python3 server.py

# Build Docker
docker build -t iiko-server-mcp .

Adding a Tool

1. Write a handler with the @tool("name", "description", input_schema) decorator
2. Add "name" to the appropriate category in ENDPOINT_CATALOG
3. Python will auto-register it — no other wiring needed

License

MIT — see LICENSE