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:

API Key - Get from SmartKasa dashboard or support
Phone Number - Your registered phone (e.g., 380501234567)
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:

Each MCP client spawns a separate process for this server
Process memory is isolated - credentials cannot leak between users
When the process ends, all credentials are cleared
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:

Configure credentials in environment variables
Server auto-authenticates on startup if env vars are set
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

Create new service in Coolify
Select "Docker Compose" or "Dockerfile"
Point to your repository
Add environment variables in Coolify UI
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

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

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

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

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

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

Безпека

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

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

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

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

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

Як це працює

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

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

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

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

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

Налаштуйте дані у змінних оточення
Сервер автоматично авторизується при запуску
Або повторно задайте дані через 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

Конфігурація у файлі claude_desktop_config.json

Вірно налаштований і запущений MCP smartkasa

Усі доступні інструменти MCP smartkasa

Не забудьте увімкнути MCP smartkasa в Connectors

Помічник ШІ уже розуміє які опції йому доступні і допоможе розібратися

Не забудьте ввести дані для авторизації, це повідомлення краще зберегти для повторного використання наступного разу коли повернетеся до цього чату

Тепер можете спілкуватися зі своєю СмартКасою в текстовому форматі

Через чат можна отримати та оновити будь-яку інформацію в кабінеті

Ліцензія

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

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

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:

API Key - Get from SmartKasa dashboard or support
Phone Number - Your registered phone (e.g., 380501234567)
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:

Each MCP client spawns a separate process for this server
Process memory is isolated - credentials cannot leak between users
When the process ends, all credentials are cleared
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:

Configure credentials in environment variables
Server auto-authenticates on startup if env vars are set
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

Create new service in Coolify
Select "Docker Compose" or "Dockerfile"
Point to your repository
Add environment variables in Coolify UI
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

Огляд

🏪 Магазинами - створення, оновлення, керування точками продажу
📦 Товарами - повне управління складом з категоріями
🧾 Чеками - продажі та фіскальні операції
👥 Працівниками - управління персоналом з ролями
📊 Звітами - 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

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

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

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

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

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

Безпека

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

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

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

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

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

Як це працює

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

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

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

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

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

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

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

"Authentication failed: 401"

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

"Connection timeout"

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

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

export SMARTKASA_LOG_LEVEL=DEBUG

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

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

Як це працює

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

Платформа	Придатність	Примітки
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

Конфігурація у файлі claude_desktop_config.json

Вірно налаштований і запущений MCP smartkasa

Усі доступні інструменти MCP smartkasa

Не забудьте увімкнути MCP smartkasa в Connectors

Помічник ШІ уже розуміє які опції йому доступні і допоможе розібратися

Тепер можете спілкуватися зі своєю СмартКасою в текстовому форматі

Через чат можна отримати та оновити будь-яку інформацію в кабінеті

Ліцензія

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

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