SmartKasa MCP Server

Production-ready Model Context Protocol (MCP) server for SmartKasa POS API

🇺🇦 Українська версія нижче

Overview

SmartKasa MCP Server enables AI assistants (Claude, GPT, etc.) to interact with SmartKasa - Ukrainian POS system with fiscal compliance. Through natural language, you can manage:

• 🏪 Shops - Create, update, manage retail locations
• 📦 Products - Full inventory management with categories
• 🧾 Receipts - Sales transactions and fiscal operations
• 👥 Employees - Staff management with roles
• 📊 Reports - Z-reports and sales statistics
• 💳 Terminals - POS terminal configuration

Features

• ✅ 58 API tools covering all SmartKasa endpoints
• ✅ HTTP/2 with connection pooling for high performance
• ✅ Automatic token refresh with exponential backoff
• ✅ Rate limiting protection with smart retries
• ✅ Secure credential handling - memory-only storage
• ✅ Multi-user support via process isolation
• ✅ Structured logging for debugging
• ✅ Two transport modes: stdio (local) and SSE (remote server)
• ✅ Docker support for easy deployment

---

How MCP Works

⚠️ Important: You do NOT need to manually run this server!

MCP uses stdio transport by default - your LLM client (Claude Desktop, Cursor, etc.) automatically starts the server as a child process and communicates via stdin/stdout.

┌─────────────────────────────────────────────────────────┐
│  LLM Client (Claude Desktop / Cursor / VS Code)         │
│                                                         │
│  1. Reads your config file                              │
│  2. Spawns: python smartkasa-mcp-server.py              │
│  3. Communicates via stdin/stdout                       │
│  4. Server runs as long as client is open               │
└─────────────────────────────────────────────────────────┘

You only configure the path - the client handles everything else.

---

Quick Start

1. Installation

# Clone the repository
git clone https://github.com/1212bogdan/smartkasa-mcp-server.git
cd smartkasa-mcp-server

# Create virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

2. Get SmartKasa Credentials

You need three things from SmartKasa:

1. API Key - Get from SmartKasa dashboard or support
2. Phone Number - Your registered phone (e.g., 380501234567)
3. Password - Your account password

3. Configure Your LLM Client

See Client Configuration section below for your specific client.

---

Client Configuration

Claude Desktop (macOS)

Edit ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "smartkasa": {
      "command": "/path/to/venv/bin/python",
      "args": ["/path/to/smartkasa-mcp-server/smartkasa-mcp-server.py"],
      "env": {
        "SMARTKASA_API_KEY": "your_api_key_here",
        "SMARTKASA_PHONE": "380501234567",
        "SMARTKASA_PASSWORD": "your_password"
      }
    }
  }
}

Claude Desktop (Windows)

Edit %APPDATA%\Claude\claude_desktop_config.json:

{
  "mcpServers": {
    "smartkasa": {
      "command": "C:\\path\\to\\venv\\Scripts\\python.exe",
      "args": ["C:\\path\\to\\smartkasa-mcp-server\\smartkasa-mcp-server.py"],
      "env": {
        "SMARTKASA_API_KEY": "your_api_key_here",
        "SMARTKASA_PHONE": "380501234567",
        "SMARTKASA_PASSWORD": "your_password"
      }
    }
  }
}

Claude Desktop (Linux)

Edit ~/.config/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "smartkasa": {
      "command": "/path/to/venv/bin/python",
      "args": ["/path/to/smartkasa-mcp-server/smartkasa-mcp-server.py"],
      "env": {
        "SMARTKASA_API_KEY": "your_api_key_here",
        "SMARTKASA_PHONE": "380501234567",
        "SMARTKASA_PASSWORD": "your_password"
      }
    }
  }
}

VS Code with Continue Extension

Add to ~/.continue/config.json:

{
  "experimental": {
    "modelContextProtocolServers": [
      {
        "transport": {
          "type": "stdio",
          "command": "/path/to/venv/bin/python",
          "args": ["/path/to/smartkasa-mcp-server/smartkasa-mcp-server.py"]
        }
      }
    ]
  }
}

Cursor IDE

Add to Cursor settings (Cmd/Ctrl + , → search "MCP"):

{
  "mcp.servers": {
    "smartkasa": {
      "command": "/path/to/venv/bin/python",
      "args": ["/path/to/smartkasa-mcp-server/smartkasa-mcp-server.py"]
    }
  }
}

Cline (VS Code Extension)

Configure in Cline settings panel:

• Server Name: smartkasa
• Command: /path/to/venv/bin/python
• Arguments: /path/to/smartkasa-mcp-server/smartkasa-mcp-server.py

---

Usage Guide

First Time Setup

If you didn't configure environment variables, set credentials via chat:

Please set my SmartKasa credentials:
- API Key: sk_live_xxxxx
- Phone: 380501234567
- Password: mypassword

Then authenticate and show my shops.

Example Conversations

List all products:

Show me all products in my SmartKasa account

Create a new product:

Create a new product called "Espresso" with price 45 UAH,
tax group 1 (20% VAT), sold by units (not weight)

Get sales report:

Show me sales statistics for the last week for shop ID 123

Check inventory:

What products have low stock in my main shop?

Manage employees:

List all employees with their roles, then show me details for employee ID 5

---

Available Tools (58 total)

Authentication (4 tools)

Tool	Description
smartkasa_set_credentials	Set API key, phone, password
smartkasa_authenticate	Authenticate and get token
smartkasa_get_status	Check auth status and expiry
smartkasa_logout	Logout and clear session

Terminals (4 tools)

Tool	Description
smartkasa_terminals_list	List all POS terminals
smartkasa_terminals_get	Get terminal by ID
smartkasa_terminals_update	Update terminal config
smartkasa_terminals_delete	Delete terminal

Shops (6 tools)

Tool	Description
smartkasa_shops_list	List all shops
smartkasa_shops_get	Get shop by ID
smartkasa_shops_create	Create new shop
smartkasa_shops_update	Update shop
smartkasa_shops_delete	Delete shop
smartkasa_shops_employees	List shop employees

Employees (5 tools)

Tool	Description
smartkasa_employees_list	List all employees
smartkasa_employees_get	Get employee by ID
smartkasa_employees_create	Create employee
smartkasa_employees_update	Update employee
smartkasa_employees_delete	Delete employee

Categories (6 tools)

Tool	Description
smartkasa_categories_list	List categories
smartkasa_categories_create	Create category
smartkasa_categories_update	Update category
smartkasa_categories_delete	Delete category
smartkasa_categories_batch_create	Batch create
smartkasa_categories_batch_delete	Batch delete

Products (8 tools)

Tool	Description
smartkasa_products_list	Search/list products
smartkasa_products_get	Get product by UUID
smartkasa_products_create	Create product
smartkasa_products_update	Update product
smartkasa_products_delete	Delete product
smartkasa_products_batch_create	Batch create
smartkasa_products_batch_delete	Batch delete

Inventory Cards (5 tools)

Tool	Description
smartkasa_cards_list	List inventory cards
smartkasa_cards_get	Get card by ID
smartkasa_cards_create	Create card
smartkasa_cards_update	Update stock
smartkasa_cards_delete	Delete card

Receipts (7 tools)

Tool	Description
smartkasa_receipts_list	List receipts
smartkasa_receipts_get	Get receipt by UUID
smartkasa_receipts_create	Create receipt
smartkasa_receipts_update	Update receipt
smartkasa_receipts_delete	Delete receipt
smartkasa_receipts_batch_create	Batch create
smartkasa_receipts_batch_delete	Batch delete

Reports (2 tools)

Tool	Description
smartkasa_reports_z_reports	Get Z-reports
smartkasa_reports_product_sales	Sales statistics

Other Tools

• smartkasa_unit_types_list - Unit types
• smartkasa_subgroups_* - Product subgroups (4 tools)
• smartkasa_import_* - Product import (3 tools)
• smartkasa_shifts_* - Fiscal shifts (2 tools)
• smartkasa_transactions_get - Payment transactions

---

Security

Credential Storage

🔐 Credentials are stored in memory only and are never written to disk by the server.

The security model:

1. Each MCP client spawns a separate process for this server
2. Process memory is isolated - credentials cannot leak between users
3. When the process ends, all credentials are cleared
4. Tokens auto-expire (typically 12 hours for access, 30 days for refresh)

Environment Variables

Variable	Description
SMARTKASA_API_KEY	Your SmartKasa API key
SMARTKASA_PHONE	Phone number (e.g., 380501234567)
SMARTKASA_PASSWORD	Account password
SMARTKASA_LOG_LEVEL	Logging level (DEBUG/INFO/WARNING/ERROR)
SMARTKASA_BASE_URL	API URL (default: https://core.smartkasa.ua)

---

Multi-User Architecture

How It Works

┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│   User Alice    │     │    User Bob     │     │   User Carol    │
│  (Claude App)   │     │   (VS Code)     │     │   (Cursor)      │
└────────┬────────┘     └────────┬────────┘     └────────┬────────┘
         │                       │                       │
         ▼                       ▼                       ▼
┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│  MCP Process 1  │     │  MCP Process 2  │     │  MCP Process 3  │
│  (Alice's creds)│     │  (Bob's creds)  │     │ (Carol's creds) │
└─────────────────┘     └─────────────────┘     └─────────────────┘
         │                       │                       │
         └───────────────────────┴───────────────────────┘
                                 │
                                 ▼
                    ┌───────────────────────┐
                    │   SmartKasa API       │
                    │ core.smartkasa.ua     │
                    └───────────────────────┘

Key points:

• Each user's LLM client spawns its own MCP server process
• Credentials are isolated in process memory
• No session conflicts between users
• Process termination = automatic cleanup

Session Persistence

⚠️ Sessions do NOT persist across:

• Application restarts
• System reboots
• Process crashes

To maintain access:

1. Configure credentials in environment variables
2. Server auto-authenticates on startup if env vars are set
3. Or re-set credentials via smartkasa_set_credentials tool

---

Troubleshooting

Common Issues

"Import mcp could not be resolved"

pip install mcp

"Authentication failed: 401"

• Verify API key is correct
• Check phone number format (no + prefix, just 380...)
• Verify password

"Connection timeout"

• Check internet connection
• Verify https://core.smartkasa.ua is accessible
• Try increasing SMARTKASA_REQUEST_TIMEOUT

"Rate limited"

• Server automatically handles this with retry
• Reduce request frequency if persistent

Debug Mode

Enable verbose logging:

export SMARTKASA_LOG_LEVEL=DEBUG

Or in config:

{
  "env": {
    "SMARTKASA_LOG_LEVEL": "DEBUG"
  }
}

---

Development

Running Tests

pip install pytest pytest-asyncio
pytest tests/

Local Development

# Run server directly
python smartkasa-mcp-server.py

# With debug logging
SMARTKASA_LOG_LEVEL=DEBUG python smartkasa-mcp-server.py

---

Remote Deployment (Server Mode)

For hosting on a server, use SSE (Server-Sent Events) transport instead of stdio.

Deployment Options

Platform	Suitability	Notes
Docker + VPS	✅ Best	Full control, persistent connections
Coolify	✅ Excellent	Easy Docker deployment
Railway	✅ Good	Supports long-running processes
Fly.io	✅ Good	Global edge deployment
Render	✅ Good	Free tier available
AWS ECS/Fargate	✅ Good	Enterprise-grade
Vercel	❌ No	Serverless, no persistent connections
Cloudflare Workers	❌ No	No long-running processes
AWS Lambda	❌ No	Timeout limits, no SSE

Option 1: Docker (Recommended)

# Build image
docker build -t smartkasa-mcp .

# Run with credentials
docker run -d \
  --name smartkasa-mcp \
  -p 8080:8080 \
  -e SMARTKASA_API_KEY="your_api_key" \
  -e SMARTKASA_PHONE="380501234567" \
  -e SMARTKASA_PASSWORD="your_password" \
  --restart unless-stopped \
  smartkasa-mcp

Option 2: Docker Compose

Create .env file:

SMARTKASA_API_KEY=your_api_key
SMARTKASA_PHONE=380501234567
SMARTKASA_PASSWORD=your_password

Run:

docker-compose up -d

Option 3: Coolify

1. Create new service in Coolify
2. Select "Docker Compose" or "Dockerfile"
3. Point to your repository
4. Add environment variables in Coolify UI
5. Deploy

Option 4: Direct Python (with systemd)

Create /etc/systemd/system/smartkasa-mcp.service:

[Unit]
Description=SmartKasa MCP Server
After=network.target

[Service]
Type=simple
User=www-data
WorkingDirectory=/opt/smartkasa-mcp-server
Environment=SMARTKASA_API_KEY=your_key
Environment=SMARTKASA_PHONE=380501234567
Environment=SMARTKASA_PASSWORD=your_password
Environment=SMARTKASA_TRANSPORT=sse
ExecStart=/opt/smartkasa-mcp-server/venv/bin/python smartkasa-mcp-server.py --transport sse
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target

Enable and start:

sudo systemctl enable smartkasa-mcp
sudo systemctl start smartkasa-mcp

Option 5: Process Manager (PM2)

# Install PM2
npm install -g pm2

# Start server
pm2 start smartkasa-mcp-server.py \
  --name smartkasa-mcp \
  --interpreter python \
  -- --transport sse --port 8080

# Save and enable startup
pm2 save
pm2 startup

HTTPS with Reverse Proxy

For production, put behind nginx/Caddy with HTTPS:

Caddy (automatic HTTPS):

mcp.yourdomain.com {
    reverse_proxy localhost:8080
}

Nginx:

server {
    listen 443 ssl http2;
    server_name mcp.yourdomain.com;

    ssl_certificate /path/to/cert.pem;
    ssl_certificate_key /path/to/key.pem;

    location / {
        proxy_pass http://localhost:8080;
        proxy_http_version 1.1;
        proxy_set_header Connection "";
        proxy_buffering off;
        proxy_cache off;
        # SSE specific
        proxy_set_header Cache-Control no-cache;
        proxy_read_timeout 86400s;
    }
}

---

Connecting to Remote MCP Server

Claude Desktop (Remote SSE)

Edit config to use SSE transport:

{
  "mcpServers": {
    "smartkasa": {
      "transport": {
        "type": "sse",
        "url": "https://mcp.yourdomain.com/sse"
      }
    }
  }
}

VS Code with Continue (Remote)

{
  "experimental": {
    "modelContextProtocolServers": [
      {
        "transport": {
          "type": "sse",
          "url": "https://mcp.yourdomain.com/sse"
        }
      }
    ]
  }
}

Health Check Endpoint

Your remote server exposes /health endpoint:

curl https://mcp.yourdomain.com/health
# {"status": "healthy", "server": "smartkasa-mcp", "transport": "sse", "authenticated": true}

---

License

MIT License - see LICENSE file.

---

<a name="ukrainian"></a>SmartKasa MCP Server (Українська)

Production-ready MCP сервер для SmartKasa POS API

Огляд

SmartKasa MCP Server дозволяє AI-асистентам (Claude, GPT тощо) працювати з SmartKasa - українською касовою системою з фіскалізацією. Через звичайну мову ви можете керувати:

• 🏪 Магазинами - створення, оновлення, керування точками продажу
• 📦 Товарами - повне управління складом з категоріями
• 🧾 Чеками - продажі та фіскальні операції
• 👥 Працівниками - управління персоналом з ролями
• 📊 Звітами - Z-звіти та статистика продажів
• 💳 Терміналами - конфігурація POS терміналів

Швидкий старт

1. Встановлення

# Клонуйте репозиторій
git clone https://github.com/1212bogdan/smartkasa-mcp-server.git
cd smartkasa-mcp-server

# Створіть віртуальне середовище
python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate

# Встановіть залежності
pip install -r requirements.txt

2. Отримайте дані для SmartKasa

Вам потрібні:

1. API Key - отримайте в особистому кабінеті SmartKasa або через підтримку
2. Номер телефону - ваш зареєстрований номер (наприклад, 380501234567)
3. Пароль - пароль вашого облікового запису

3. Налаштуйте ваш LLM клієнт

Claude Desktop (macOS)

Редагуйте ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "smartkasa": {
      "command": "/шлях/до/venv/bin/python",
      "args": ["/шлях/до/smartkasa-mcp-server/smartkasa-mcp-server.py"],
      "env": {
        "SMARTKASA_API_KEY": "ваш_api_ключ",
        "SMARTKASA_PHONE": "380501234567",
        "SMARTKASA_PASSWORD": "ваш_пароль"
      }
    }
  }
}

Claude Desktop (Windows)

Редагуйте %APPDATA%\Claude\claude_desktop_config.json:

{
  "mcpServers": {
    "smartkasa": {
      "command": "C:\\шлях\\до\\venv\\Scripts\\python.exe",
      "args": ["C:\\шлях\\до\\smartkasa-mcp-server\\smartkasa-mcp-server.py"],
      "env": {
        "SMARTKASA_API_KEY": "ваш_api_ключ",
        "SMARTKASA_PHONE": "380501234567",
        "SMARTKASA_PASSWORD": "ваш_пароль"
      }
    }
  }
}

Приклади використання

Перша авторизація (якщо не налаштовані env vars):

Встанови мої дані SmartKasa:
- API Key: sk_live_xxxxx
- Телефон: 380501234567
- Пароль: мій_пароль

Потім авторизуйся і покажи мої магазини.

Показати всі товари:

Покажи всі товари в моєму акаунті SmartKasa

Створити новий товар:

Створи новий товар "Еспресо" з ціною 45 грн,
група оподаткування 1 (ПДВ 20%), продається штуками

Звіт по продажах:

Покажи статистику продажів за останній тиждень для магазину ID 123

Перевірити залишки:

Які товари мають низький запас в головному магазині?

Безпека

Зберігання даних

🔐 Дані зберігаються тільки в пам'яті і ніколи не записуються на диск сервером.

Модель безпеки:

1. Кожен LLM клієнт запускає окремий процес сервера
2. Пам'ять процесів ізольована - дані не можуть витікати між користувачами
3. Коли процес завершується, всі дані очищаються
4. Токени автоматично закінчуються (зазвичай 12 годин для access, 30 днів для refresh)

Мультикористувацька архітектура

Як це працює

• Кожен LLM клієнт користувача запускає власний процес MCP сервера
• Дані авторизації ізольовані в пам'яті процесу
• Немає конфліктів сесій між користувачами
• Завершення процесу = автоматичне очищення

Збереження сесій

⚠️ Сесії НЕ зберігаються після:

• Перезапуску додатка
• Перезавантаження системи
• Аварійного завершення процесу

Для збереження доступу:

1. Налаштуйте дані у змінних оточення
2. Сервер автоматично авторизується при запуску
3. Або повторно задайте дані через smartkasa_set_credentials

Усунення проблем

"Authentication failed: 401"

• Перевірте правильність API ключа
• Перевірте формат номера (без +, просто 380...)
• Перевірте пароль

"Connection timeout"

• Перевірте з'єднання з інтернетом
• Перевірте доступність https://core.smartkasa.ua

Режим налагодження

export SMARTKASA_LOG_LEVEL=DEBUG

---

Віддалений розгортання (Серверний режим)

Для хостингу на сервері використовуйте SSE (Server-Sent Events) transport.

Як це працює

При локальному використанні (stdio) - LLM клієнт сам запускає сервер.
При віддаленому (SSE) - сервер працює постійно, клієнти підключаються по HTTP.

Варіанти розгортання

Платформа	Придатність	Примітки
Docker + VPS	✅ Найкраще	Повний контроль
Coolify	✅ Відмінно	Легке Docker розгортання
Railway	✅ Добре	Підтримує long-running
Fly.io	✅ Добре	Global edge
Vercel	❌ Ні	Serverless, немає SSE
Lambda	❌ Ні	Timeout, немає SSE

Docker

# Збірка
docker build -t smartkasa-mcp .

# Запуск
docker run -d \
  --name smartkasa-mcp \
  -p 8080:8080 \
  -e SMARTKASA_API_KEY="ваш_ключ" \
  -e SMARTKASA_PHONE="380501234567" \
  -e SMARTKASA_PASSWORD="ваш_пароль" \
  --restart unless-stopped \
  smartkasa-mcp

Docker Compose

# Створіть .env файл з credentials
docker-compose up -d

Systemd (Linux сервер)

Створіть /etc/systemd/system/smartkasa-mcp.service:

[Unit]
Description=SmartKasa MCP Server
After=network.target

[Service]
Type=simple
User=www-data
WorkingDirectory=/opt/smartkasa-mcp-server
Environment=SMARTKASA_API_KEY=ваш_ключ
Environment=SMARTKASA_TRANSPORT=sse
ExecStart=/opt/smartkasa-mcp-server/venv/bin/python smartkasa-mcp-server.py --transport sse
Restart=always

[Install]
WantedBy=multi-user.target

Підключення до віддаленого сервера

У конфігу Claude Desktop:

{
  "mcpServers": {
    "smartkasa": {
      "transport": {
        "type": "sse",
        "url": "https://mcp.yourdomain.com/sse"
      }
    }
  }
}

---

Скріншоти

Робота зі SmartKasa API через Claude Desktop з локально запущеним MCP

---

Ліцензія

MIT License - дивіться файл LICENSE.

---

Зроблено з ❤️ для української спільноти розробників