SmartKasa MCP Server

SmartKasa MCP服务器

用于SmartKasa POS API的生产就绪模型上下文协议（MCP）服务器

  

🇺🇦 下面的中文版本

概述

SmartKasa MCP服务器使AI助手（Claude、GPT等）能够与 SmartKasa -符合财政规定的乌克兰POS系统。通过自然语言，您可以管理：

• 🏪 商店 -创建、更新和管理零售地点
• 📦 产品 -分类全面库存管理
• 🧾 收据 -销售交易和财务操作
• 👥 员工 -有角色的员工管理
• 📊 报告 -Z报告和销售统计
• 💳 终端 -POS终端配置

特性

• ✅ 58 API工具 覆盖所有SmartKasa端点
• ✅ HTTP/2 通过连接池实现高性能
• ✅ 自动令牌刷新 指数回退
• ✅ 速率限制保护 智能重试
• ✅ 安全的凭证处理 -仅内存存储
• ✅ 多用户支持 通过过程隔离
• ✅ 结构化日志记录 用于调试
• ✅ 两种运输方式：stdio（本地）和SSE（远程服务器）
• ✅ Docker支持 便于部署

______________________________________________________________________

MCP的工作原理

⚠️ 重要：您不需要手动运行此服务器！

MCP使用 stdio传输 默认情况下，您的LLM客户端（Claude Desktop、Cursor等）会自动将服务器作为子进程启动，并通过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               │
└─────────────────────────────────────────────────────────┘

您只需配置路径 -客户处理其他一切。

______________________________________________________________________

快速开始

1.安装

# 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.获取SmartKasa凭据

您需要SmartKasa提供三样东西：

1. API密钥 -从SmartKasa仪表板或支持获取
2. 电话号码 -您的注册电话（例如。， 380501234567)
3. 密码 -您的帐户密码

3.配置LLM客户端

看 客户端配置 以下部分针对您的特定客户。

______________________________________________________________________

客户端配置

克劳德桌面（macOS）

编辑 ~/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"
      }
    }
  }
}

克劳德桌面（Windows）

编辑 %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"
      }
    }
  }
}

克劳德桌面（Linux）

编辑 ~/.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"
      }
    }
  }
}

带有Continue扩展名的VS代码

添加到 ~/.continue/config.json:

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

光标IDE

添加到光标设置(Cmd/Ctrl + , → 搜索“MCP”）：

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

Cline（VS代码扩展）

在Cline设置面板中配置：

• 服务器名称： smartkasa
• 命令： /path/to/venv/bin/python
• 论据： /path/to/smartkasa-mcp-server/smartkasa-mcp-server.py

______________________________________________________________________

使用指南

首次设置

如果您没有配置环境变量，请通过聊天设置凭据：

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

Then authenticate and show my shops.

对话示例

列出所有产品：

Show me all products in my SmartKasa account

创建新产品：

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

获取销售报告：

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

检查库存：

What products have low stock in my main shop?

管理员工：

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

______________________________________________________________________

可用工具（共58个）

身份验证（4个工具）

端子（4个工具）

商店（6工具）

员工（5个工具）

类别（6个工具）

产品（8工具）

库存卡（5个工具）

收据（7个工具）

报告（2个工具）

其他工具

• smartkasa_unit_types_list -单位类型
• smartkasa_subgroups_* -产品子组（4个工具）
• smartkasa_import_* -产品导入（3个工具）
• smartkasa_shifts_* -财政转移（2个工具）
• smartkasa_transactions_get -付款交易

______________________________________________________________________

安全

凭据存储

🔐 凭据仅存储在内存中 并且永远不会被服务器写入磁盘。

安全模型：

1. 每个MCP客户端生成一个 独立进程 对于此服务器
2. 进程内存是隔离的-凭据不能在用户之间泄漏
3. 当流程结束时，所有凭据都将被清除
4. 令牌自动过期（通常访问12小时，刷新30天）

环境变量

______________________________________________________________________

多用户架构

运作原理

┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│   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     │
                    └───────────────────────┘

要点：

• 每个用户的LLM客户端生成其 自己的MCP服务器进程
• 凭据在进程内存中隔离
• 用户之间没有会话冲突
• 进程终止=自动清理

会话保持

⚠️ 会话不持久 穿过：

• 应用程序重新启动
• 系统重新启动
• 进程崩溃

要保持访问权限：

1. 在环境变量中配置凭据
2. 如果设置了env变量，服务器将在启动时自动进行身份验证
3. 或通过以下方式重新设置凭据 smartkasa_set_credentials 工具

______________________________________________________________________

故障排除

常见问题

“无法解析导入mcp”

pip install mcp

“身份验证失败：401”

• 验证API密钥是否正确
• 检查电话号码格式（无+前缀，只有380…）
• 验证密码

“连接超时”

• 检查互联网连接
• 验证https://core.smartkasa.ua可访问的
• 尝试增加 SMARTKASA_REQUEST_TIMEOUT

“价格有限”

• 服务器会自动处理此问题并重试
• 如果持续存在，请降低请求频率

调试模式

启用详细日志记录：

export SMARTKASA_LOG_LEVEL=DEBUG

或者在配置中：

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

______________________________________________________________________

发展

运行测试

pip install pytest pytest-asyncio
pytest tests/

本地开发

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

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

______________________________________________________________________

远程部署（服务器模式）

对于在服务器上托管，请使用 SSE（服务器发送事件）传输 而不是stdio。

部署选项

选项1:Docker（推荐）

# 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

选项2：Docker编写

创建 .env 文件：

SMARTKASA_API_KEY=your_api_key
SMARTKASA_PHONE=380501234567
SMARTKASA_PASSWORD=your_password

运行：

docker-compose up -d

选项3：冷却

1. 在Coolify中创建新服务
2. 选择“Docker编写”或“Dockerfile”
3. 指向您的存储库
4. 在Coolify UI中添加环境变量
5. 部署

选项4：直接Python（带systemd）

创建 /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

启用并启动：

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

选项5：流程管理器（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

对于生产，使用HTTPS将nginx/Caddy放在后面：

球童（自动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;
    }
}

______________________________________________________________________

连接到远程MCP服务器

克劳德桌面（远程SSE）

编辑配置以使用SSE传输：

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

VS代码继续（远程）

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

健康检查端点

您的远程服务器暴露 /health 端点：

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

______________________________________________________________________

许可证

MIT许可证-请参阅 许可证 文件。

______________________________________________________________________

SmartKasa MCP Server（中文）

生产就绪MCP

概述

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密钥 - 在SmartKasa个人办公室或通过支持获取
2. 电话号码 您的注册号码（例如： 380501234567)
3. 密码 - 您的帐户密码

3. 设置您的LLM客户端

克劳德桌面（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": "ваш_пароль"
      }
    }
  }
}

克劳德桌面（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小时，刷新30天）

多用户架构

它是如何工作的

• 每个LLM客户端用户运行 自定义 MCP 服务器进程
• 授权数据在进程内存中隔离
• 用户之间没有会话冲突
• 完成过程=自动清洁

保存会话

⚠️ 会话未保存 之后 ：

• 重新启动应用程序
• 重新启动系统
• 紧急结束过程

为了保持访问权限：

1. 在可变环境中配置数据
2. 服务器启动时自动授权
3. 或者通过重新输入数据 smartkasa_set_credentials

解决问题

“身份验证失败：401”

• 检查API密钥的有效性
• 检查号码格式（没有+，只有380…）
• 检查密码

“连接超时”

• 检查您的互联网连接
• 检查可用性https://core.smartkasa.ua

配置模式

export SMARTKASA_LOG_LEVEL=DEBUG

______________________________________________________________________

远程部署（ 服务器模式）

对于服务器托管，请使用 SSE（服务器发送事件）传输.

它是如何工作的

在本地使用（stdio）时，LLM客户端自行启动服务器。\ 在远程（SSE）时，服务器持续运行，客户端通过HTTP连接。

部署选项

码头工人

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

______________________________________________________________________

屏幕截图

通过本地运行 MCP 的 Claude Desktop 使用 SmartKasa API

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

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

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

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

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

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

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

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

______________________________________________________________________

许可证

MIT License - 查看文件 许可证.

______________________________________________________________________

_由❤️ 乌克兰开发者社区_