BILLZ MCP Server

MCP server for the BILLZ POS/Retail API 2.0.

Modes

Set via BILLZ_MCP_MODE environment variable.

Related MCP server: MCP Business AI Transformation

Setup

1. Build

cd billz_mcp
npm install
npm run build

2. Get your API key

In BILLZ Admin → Settings → Integrations → create an API key. Grant the key read access to Products, Sales, Reports, etc. (permission matrix in BILLZ Admin).

2b. Verify read APIs (optional)

Calls the same HTTP paths as BILLZ_MCP_MODE=analytics (18 read tools). Use the same secret you pass to MCP:

cd billz_mcp
npm install
BILLZ_SECRET_KEY='your_key' npm run smoke:read

You can also put BILLZ_SECRET_KEY=... in billz_mcp/.env. Exit code 0 means every check passed.

3. Add to Cursor (or any MCP client)

{
  "mcpServers": {
    "billz": {
      "command": "node",
      "args": ["/absolute/path/to/billz_mcp/dist/index.js"],
      "env": {
        "BILLZ_SECRET_KEY": "your_secret_key_here",
        "BILLZ_MCP_MODE": "analytics"
      }
    }
  }
}

Environment Variables

Analytics Mode (default) — 18 tools

Products (2)

Sales (3)

Customers (3)

Reports (6)

Reference Data (4)

Full Mode — additional tools

Set BILLZ_MCP_MODE=full to unlock all 80+ tools including:

• Products: create, patch custom fields

• Sales: create draft, add products, apply discount, attach customer, complete, postpone, manage drafts

• Customers: create, update, set balance, loyalty cards

• Supplier Orders: create, add products, update, send

• Transfers: create, add products, send, cancel, accept, update

• Imports: bulk import products

• Promotions: list promos, details, promo products

• Write-offs: create, add products, cancel, complete, reasons

• Stocktaking: list sessions

• Certificates/Gift Cards: search, create, add/remove from sale, pay

• Reports: 19 additional report tools (transactions, performance, imports, suppliers, etc.)

• Auxiliary: company, users, suppliers, measurement units, cashboxes, payment types, currencies

MCP Resources

API documentation is exposed as MCP resources via billz://docs/{key} (available in both modes).

Project Structure

src/
  index.ts              Server init, mode gating, module registration
  billz-client.ts       HTTP client with JWT auth & 401 retry
  helpers.ts            Shared ok() helper, McpMode type
  resources.ts          MCP resources (API docs)
  tools/
    products.ts         2 analytics + 3 full
    customers.ts        3 analytics + 7 full
    sales.ts            3 analytics + 12 full
    reports.ts          6 analytics + 19 full
    auxiliary.ts        4 analytics + 10 full
    orders.ts           6 full-only
    transfers.ts        8 full-only
    imports.ts          2 full-only
    promotions.ts       3 full-only
    writeoffs.ts        5 full-only
    stocktaking.ts      1 full-only
    certificates.ts     5 full-only