Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@billz_mcp show top selling products this month"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
MCP server for the BILLZ POS/Retail API 2.0.
Mode | Tools | Description |
| 18 | Read-only analytics & lookup — safe for AI agents |
| 80+ | All tools including write operations (sales, write-offs, transfers, etc.) |
Set via BILLZ_MCP_MODE environment variable.
Related MCP server: MCP Business AI Transformation
cd billz_mcp
npm install
npm run buildIn BILLZ Admin → Settings → Integrations → create an API key. Grant the key read access to Products, Sales, Reports, etc. (permission matrix in BILLZ Admin).
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:readYou can also put BILLZ_SECRET_KEY=... in billz_mcp/.env. Exit code 0 means every check passed.
{
"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"
}
}
}
}Variable | Required | Default | Description |
| Yes | — | API integration key from BILLZ Admin |
| No |
|
|
| No | built-in | Platform ID header value |
Tool | Description |
| List products (delta sync via |
| Advanced product search with filters |
Tool | Description |
| List completed sales |
| Single sale deep dive |
| Advanced sales search (v3) |
Tool | Description |
| List/search customers |
| Single customer detail |
| Debt overview |
Tool | Description |
| KPI dashboard (sales, products, customers) |
| KPI totals/sums |
| Sales by product |
| Customer analytics |
| Profit & loss |
| Inventory levels by date |
Tool | Description |
| Shop list |
| Product categories |
| Product brands |
| Custom field definitions |
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
API documentation is exposed as MCP resources via billz://docs/{key} (available in both modes).
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-onlyGet list of product brands
Inputs: page, limit, search.
Get product categories
Inputs: page, limit, search, is_deleted.
Get product custom field definitions
Inputs: limit.
Get details of a specific sale
Inputs: order_id (required).
Get list of shops
Inputs: limit, only_allowed.
Customer statistics report table
Inputs: start_date (required), page, limit, currency, +2 more.
General summary report totals (sums)
Inputs: start_date (required), currency, end_date, shop_ids.
Profit and loss report
Inputs: start_date (required), currency, end_date, shop_ids.
Search sales with advanced filters (v3 endpoint)
Inputs: page, limit, search, status, +5 more.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
Scored across 9 tools
Most tools target clearly distinct resources: product characteristics, sale details, sales search, reports, shops, categories, and brands. The main source of potential confusion is between billz_report_general_totals and billz_report_profit_loss, which both deal with aggregated financial figures, though their descriptions separate them reasonably.
Tool names follow a mostly consistent pattern of billz_ + action + resource: get_product_characteristics, get_sale_details, get_shops, get_categories, get_brands, search_sales, report_general_totals, report_customers_table, report_profit_loss. The minor inconsistency is the report_* prefix vs get_*/search_*, and report_customers_table is slightly awkward, but overall the pattern is readable and predictable.
Nine tools is well within the ideal range for an integration server. Each tool covers a distinct area of the Billz retail/ERP domain without feeling padded or redundant.
The server covers sales retrieval, reporting, and reference data like shops, categories, and brands. However, it lacks basic product catalog access (only product characteristics are available), and there is no way to list or fetch individual customers, even though customer reports exist. This leaves notable gaps in the apparent domain.
MCP server unifying ERPs, CRMs, APIs and knowledge base for Claude, ChatGPT and Gemini.
MCP Server for agents to onboard, pay, and provision services autonomously with InFlow
Hosted MCP server for live public-data APIs and Skills for AI agents.
Hosted MCP server connecting AI assistants to 9,000+ apps and 40,000+ actions via Zapier.
