Skip to main content
Glama
1212bogdan

SmartKasa MCP Server

by 1212bogdan

SmartKasa MCP Server

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

Python 3.10+ MCP License: MIT

πŸ‡ΊπŸ‡¦ Π£ΠΊΡ€Π°Ρ—Π½ΡΡŒΠΊΠ° вСрсія Π½ΠΈΠΆΡ‡Π΅

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

Related MCP server: SalesDrive MCP Server

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"

"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

# 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 + 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.


Π—Ρ€ΠΎΠ±Π»Π΅Π½ΠΎ Π· ❀️ для ΡƒΠΊΡ€Π°Ρ—Π½ΡΡŒΠΊΠΎΡ— ΡΠΏΡ–Π»ΡŒΠ½ΠΎΡ‚ΠΈ Ρ€ΠΎΠ·Ρ€ΠΎΠ±Π½ΠΈΠΊΡ–Π²

Related MCP Connectors

Related MCP Servers

  • A
    license
    Not graded
    quality
    D
    maintenance
    Enables AI assistants to interact with SalesDrive CRM, allowing order management, product queries, and more through natural language.
    Apache 2.0
  • A
    license
    A
    quality
    B
    maintenance
    Exposes the Loyverse API as MCP tools to manage stores, products, inventory, customers, receipts, and more from AI assistants.
    54
    MIT
  • F
    license
    Not graded
    quality
    C
    maintenance
    Enables AI assistants to query a retail and food-service point-of-sale database through predefined business tools for sales summaries, top products, margins, stagnant inventory, cash reconciliation, and optional stock adjustments, returning formatted markdown answers.
    -