# SmartKasa MCP Server
**Production-ready Model Context Protocol (MCP) server for SmartKasa POS API**
[](https://www.python.org/downloads/)
[](https://modelcontextprotocol.io/)
[](LICENSE)
🇺🇦 [Українська версія нижче](#ukrainian)
## Overview
SmartKasa MCP Server enables AI assistants (Claude, GPT, etc.) to interact with [SmartKasa](https://smartkasa.ua/) - 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
```bash
# 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](#client-configuration) section below for your specific client.
---
## Client Configuration
### Claude Desktop (macOS)
Edit `~/Library/Application Support/Claude/claude_desktop_config.json`:
```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`:
```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`:
```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`:
```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"):
```json
{
"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"**
```bash
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:
```bash
export SMARTKASA_LOG_LEVEL=DEBUG
```
Or in config:
```json
{
"env": {
"SMARTKASA_LOG_LEVEL": "DEBUG"
}
}
```
---
## Development
### Running Tests
```bash
pip install pytest pytest-asyncio
pytest tests/
```
### Local Development
```bash
# 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)
```bash
# 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:
```bash
SMARTKASA_API_KEY=your_api_key
SMARTKASA_PHONE=380501234567
SMARTKASA_PASSWORD=your_password
```
Run:
```bash
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`:
```ini
[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:
```bash
sudo systemctl enable smartkasa-mcp
sudo systemctl start smartkasa-mcp
```
### Option 5: Process Manager (PM2)
```bash
# 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:**
```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:
```json
{
"mcpServers": {
"smartkasa": {
"transport": {
"type": "sse",
"url": "https://mcp.yourdomain.com/sse"
}
}
}
}
```
### VS Code with Continue (Remote)
```json
{
"experimental": {
"modelContextProtocolServers": [
{
"transport": {
"type": "sse",
"url": "https://mcp.yourdomain.com/sse"
}
}
]
}
}
```
### Health Check Endpoint
Your remote server exposes `/health` endpoint:
```bash
curl https://mcp.yourdomain.com/health
# {"status": "healthy", "server": "smartkasa-mcp", "transport": "sse", "authenticated": true}
```
---
## License
MIT License - see [LICENSE](LICENSE) file.
---
# <a name="ukrainian"></a>SmartKasa MCP Server (Українська)
**Production-ready MCP сервер для SmartKasa POS API**
## Огляд
SmartKasa MCP Server дозволяє AI-асистентам (Claude, GPT тощо) працювати з [SmartKasa](https://smartkasa.ua/) - українською касовою системою з фіскалізацією. Через звичайну мову ви можете керувати:
- 🏪 **Магазинами** - створення, оновлення, керування точками продажу
- 📦 **Товарами** - повне управління складом з категоріями
- 🧾 **Чеками** - продажі та фіскальні операції
- 👥 **Працівниками** - управління персоналом з ролями
- 📊 **Звітами** - Z-звіти та статистика продажів
- 💳 **Терміналами** - конфігурація POS терміналів
## Швидкий старт
### 1. Встановлення
```bash
# Клонуйте репозиторій
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`:
```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`:
```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
### Режим налагодження
```bash
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
```bash
# Збірка
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
```bash
# Створіть .env файл з credentials
docker-compose up -d
```
### Systemd (Linux сервер)
Створіть `/etc/systemd/system/smartkasa-mcp.service`:
```ini
[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:
```json
{
"mcpServers": {
"smartkasa": {
"transport": {
"type": "sse",
"url": "https://mcp.yourdomain.com/sse"
}
}
}
}
```
---
## Скріншоти
### Робота зі SmartKasa API через Claude Desktop з локально запущеним MCP
---
## Ліцензія
MIT License - дивіться файл [LICENSE](LICENSE).
---
_Зроблено з ❤️ для української спільноти розробників_
