使用说明

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提供三样东西：

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

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个工具）

工具	说明
`smartkasa_set_credentials`	设置API密钥、电话、密码
`smartkasa_authenticate`	验证并获取令牌
`smartkasa_get_status`	检查身份验证状态和到期时间
`smartkasa_logout`	注销并清除会话

端子（4个工具）

工具	说明
`smartkasa_terminals_list`	列出所有POS终端
`smartkasa_terminals_get`	按ID获取终端
`smartkasa_terminals_update`	更新终端配置
`smartkasa_terminals_delete`	删除终端

商店（6工具）

工具	说明
`smartkasa_shops_list`	列出所有商店
`smartkasa_shops_get`	按ID购物
`smartkasa_shops_create`	创建新店铺
`smartkasa_shops_update`	更新店铺
`smartkasa_shops_delete`	删除店铺
`smartkasa_shops_employees`	列出店铺员工

员工（5个工具）

工具	说明
`smartkasa_employees_list`	列出所有员工
`smartkasa_employees_get`	按ID获取员工
`smartkasa_employees_create`	创建员工
`smartkasa_employees_update`	更新员工
`smartkasa_employees_delete`	删除员工

类别（6个工具）

工具	说明
`smartkasa_categories_list`	列出类别
`smartkasa_categories_create`	创建类别
`smartkasa_categories_update`	更新类别
`smartkasa_categories_delete`	删除类别
`smartkasa_categories_batch_create`	批量创建
`smartkasa_categories_batch_delete`	批量删除

产品（8工具）

工具	说明
`smartkasa_products_list`	搜索/列出产品
`smartkasa_products_get`	按UUID获取产品
`smartkasa_products_create`	创建产品
`smartkasa_products_update`	更新产品
`smartkasa_products_delete`	删除产品
`smartkasa_products_batch_create`	批量创建
`smartkasa_products_batch_delete`	批量删除

库存卡（5个工具）

工具	说明
`smartkasa_cards_list`	列出库存卡
`smartkasa_cards_get`	凭身份证取卡
`smartkasa_cards_create`	创建卡片
`smartkasa_cards_update`	更新库存
`smartkasa_cards_delete`	删除卡片

收据（7个工具）

工具	说明
`smartkasa_receipts_list`	列出收据
`smartkasa_receipts_get`	通过UUID获取收据
`smartkasa_receipts_create`	创建收据
`smartkasa_receipts_update`	更新收据
`smartkasa_receipts_delete`	删除收据
`smartkasa_receipts_batch_create`	批量创建
`smartkasa_receipts_batch_delete`	批量删除

报告（2个工具）

工具	说明
`smartkasa_reports_z_reports`	获取Z报告
`smartkasa_reports_product_sales`	销售统计

其他工具

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

安全

凭据存储

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

安全模型：

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

环境变量

变量	描述
`SMARTKASA_API_KEY`	您的SmartKasa API密钥
`SMARTKASA_PHONE`	电话号码（例如380501234567）
`SMARTKASA_PASSWORD`	帐户密码
`SMARTKASA_LOG_LEVEL`	日志记录级别（调试/信息/警告/错误）
`SMARTKASA_BASE_URL`	API URL（默认值：https://core.smartkasa.ua)

多用户架构

运作原理

┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│   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服务器进程
凭据在进程内存中隔离
用户之间没有会话冲突
进程终止=自动清理

会话保持

⚠️ 会话不持久 穿过：

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

要保持访问权限：

在环境变量中配置凭据
如果设置了env变量，服务器将在启动时自动进行身份验证
或通过以下方式重新设置凭据 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。

部署选项

平台	适用性	注意事项
Docker+虚拟专用服务器	✅ 最佳	完全控制，持久连接
冷却	✅ 优秀	易于部署Docker
铁路	✅ 良好	支持长时间运行的流程
Fly.io	✅ 良好	全球边缘部署
渲染	✅ 好	免费套餐可用
AWS ECS/Fargate	✅ 良好	企业级
维塞尔	❌ 否	无服务器，无持久连接
Cloudflare员工	❌ 否	没有长时间运行的进程
AWS Lambda	❌ 无	超时限制，无SSE

选项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：冷却

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

选项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数据

您需要：

API密钥 - 在SmartKasa个人办公室或通过支持获取
电话号码 您的注册号码（例如： 380501234567)
密码 - 您的帐户密码

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

检查残余：

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

安全

数据存储

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

安全模型：

每个LLM客户运行 单独的过程 服务器
进程内存隔离 - 数据不能在用户之间泄露
当过程完成时，所有数据都将被清除
令牌将自动过期（通常是访问12小时，刷新30天）

多用户架构

它是如何工作的

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

保存会话

⚠️ 会话未保存 之后：

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

为了保持访问权限：

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

解决问题

“身份验证失败：401”

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

“连接超时”

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

配置模式

export SMARTKASA_LOG_LEVEL=DEBUG

远程部署（服务器模式）

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

它是如何工作的

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

部署选项

平台	适用性	注释
Docker+虚拟专用服务器	✅ 最好的完全控制
冷却	✅ 很好	轻松的Docker部署
铁路	✅ 支持 long-running。
Fly.io	✅ 好吧	Global edge
维塞尔	❌ 没有Serverless，没有SSE。
拉姆达	❌ 没有 Timeout，没有 SSE。

码头工人

# Збірка
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 MCP服务器

概述

特性

MCP的工作原理

快速开始

1.安装

2.获取SmartKasa凭据

3.配置LLM客户端

客户端配置

克劳德桌面（macOS）

克劳德桌面（Windows）

克劳德桌面（Linux）

带有Continue扩展名的VS代码

光标IDE

Cline（VS代码扩展）

使用指南

首次设置

对话示例

可用工具（共58个）

身份验证（4个工具）

端子（4个工具）

商店（6工具）

员工（5个工具）

类别（6个工具）

产品（8工具）

库存卡（5个工具）

收据（7个工具）

报告（2个工具）

其他工具

安全

凭据存储

环境变量

多用户架构

运作原理

会话保持

故障排除

常见问题

调试模式

发展

运行测试

本地开发

远程部署（服务器模式）

部署选项

选项1:Docker（推荐）

选项2：Docker编写

选项3：冷却

选项4：直接Python（带systemd）

选项5：流程管理器（PM2）

带反向代理的HTTPS

连接到远程MCP服务器

克劳德桌面（远程SSE）

VS代码继续（远程）

健康检查端点

许可证

SmartKasa MCP Server（中文）

概述

快速启动

1. 安装

2. 获取SmartKasa数据

3. 设置您的LLM客户端

克劳德桌面（macOS）

克劳德桌面（Windows）

使用范例

安全

数据存储

多用户架构

它是如何工作的

保存会话

解决问题

配置模式

远程部署（ 服务器模式）

它是如何工作的

部署选项

码头工人

Docker Compose

Systemd （Linux 服务器）

连接到远程服务器

屏幕截图

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

远程部署（服务器模式）