home / mcp / smartkasa mcp server

SmartKasa MCP Server

Provides an MCP server to connect AI assistants with SmartKasa POS, enabling product, shop, receipt, and report management via natural language.

Installation

Add the following to your MCP client configuration file.

Configuration

View docs

{
  "mcpServers": {
    "1212bogdan-smartkasa-mcp-server": {
      "url": "https://mcp.yourdomain.com/sse",
      "headers": {
        "SMARTKASA_PHONE": "380501234567",
        "SMARTKASA_API_KEY": "sk_live_xxxxx",
        "SMARTKASA_BASE_URL": "https://core.smartkasa.ua",
        "SMARTKASA_PASSWORD": "my_password",
        "SMARTKASA_LOG_LEVEL": "DEBUG"
      }
    }
  }
}

You can connect AI copilots to SmartKasa using a dedicated MCP server that exposes SmartKasa endpoints to natural language interactions. This server handles authentication, routing, and high‑level actions such as managing shops, products, receipts, employees, reports, and terminals, while keeping credentials secure and isolated per client.

How to use

You use an MCP client (Claude Desktop, VS Code, Cursor, or other compatible tools) to communicate with the SmartKasa MCP Server. The client can start a local stdio MCP server as a child process or connect to a remote SSE server. You will authenticate once for your session and then issue natural language commands to perform tasks like listing products, creating shops, generating receipts, or viewing reports. Each user’s credentials are kept in a separate process to prevent cross‑session access, and tokens expire automatically for security.

How to install

# 1. Clone the repository
git clone https://github.com/1212bogdan/smartkasa-mcp-server.git
cd smartkasa-mcp-server

# 2. Create a virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# 3. Install dependencies
pip install -r requirements.txt

Prepare credentials in environment variables or through the client after startup. You will need an API key, your SmartKasa phone number, and your password to authenticate with SmartKasa.

Additional sections

Configuration, security, and usage notes are provided below to help you run, secure, and connect to the MCP server in local or remote environments.

Credentials and transport options are shown in explicit configuration examples. You can run the server locally with stdio or deploy it for remote access via SSE. Ensure you provide the required environment variables when starting the server.

Security is built around in-memory credential storage, per‑process isolation, and auto‑expiring tokens. Sessions do not persist across restarts, so re‑establish credentials if needed.

If you run into issues, enable debug logging to get more detail for troubleshooting.

Remote deployment and health checks are supported via an SSE endpoint and a health route to confirm status.

Available tools

smartkasa_set_credentials

Set API key, phone, and password for the MCP session

smartkasa_authenticate

Authenticate and obtain an access token for SmartKasa APIs

smartkasa_get_status

Check current authentication status and token expiry

smartkasa_logout

Logout and clear the current session

smartkasa_terminals_list

List all POS terminals

smartkasa_terminals_get

Get a terminal by ID

smartkasa_terminals_update

Update terminal configuration

smartkasa_terminals_delete

Delete a terminal

smartkasa_shops_list

List all shops

smartkasa_shops_get

Get a shop by ID

smartkasa_shops_create

Create a new shop

smartkasa_shops_update

Update a shop

smartkasa_shops_delete

Delete a shop

smartkasa_shops_employees

List employees associated with a shop

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

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 categories

smartkasa_categories_batch_delete

Batch delete categories

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 products

smartkasa_products_batch_delete

Batch delete products

smartkasa_cards_list

List inventory cards

smartkasa_cards_get

Get card by ID

smartkasa_cards_create

Create inventory card

smartkasa_cards_update

Update stock for a card

smartkasa_cards_delete

Delete card

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 receipts

smartkasa_receipts_batch_delete

Batch delete receipts

smartkasa_reports_z_reports

Get Z-reports

smartkasa_reports_product_sales

Sales statistics

smartkasa_unit_types_list

List unit types

smartkasa_subgroups_*

Product subgroup operations (4 tools)

smartkasa_import_*

Product import operations (3 tools)

smartkasa_shifts_*

Fiscal shifts operations (2 tools)

smartkasa_transactions_get

Payment transactions