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

Related MCP server: @spec2tools/stdio-mcp

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:

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

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