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)

Terminals (4 tools)

Shops (6 tools)

Employees (5 tools)

Categories (6 tools)

Products (8 tools)

Inventory Cards (5 tools)

Receipts (7 tools)

Reports (2 tools)

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

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

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.

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

# Збірка
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.

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