BILLZ MCP Bridge Server

This project acts as a "bridge" between the BILLZ 2.0 REST API (https://api-admin.billz.ai) and Claude. Through this server, Claude can read products, sales, customers, and other data from BILLZ.

1. Prerequisites

• Node.js 18+ (to run the project)

• Client ID (login) and API key (secret) obtained from BILLZ 2.0 (the two fields in the "Advanced settings" shown in the image)

• A free hosting account to make the server accessible online (e.g., Render.com or Railway.app)

Related MCP server: BizDesk MCP

2. About Endpoint Paths

✅ The authentication (login) part is confirmed and works correctly — written according to the "Аутентификация" section of the official BILLZ documentation: POST /v1/auth/login + {"secret_token": "..."}.

⚠️ The paths used for products/sales/customers (/v1/products, /v1/orders, /v1/clients, /v1/categories) are still approximate — because the "Методы" section of the BILLZ documentation has not yet been confirmed. Open this section and check the exact paths: https://billzuz.notion.site/API-c2f91aa254f94f8eb7c1b26415dcb25b

Therefore, initially use only the billz_request (generic request) tool — it works with any correct path because it only depends on proper authentication. For example, you can tell Claude: "Send a request to the GET /v1/products path via billz_request" — if the path is incorrect, an error message will appear, and I will correct it.

3. Testing on Your Computer (Optional)

cd billz-mcp-server
npm install
cp .env.example .env
# .env faylini ochib, BILLZ_LOGIN, BILLZ_SECRET va MCP_BRIDGE_SECRET
# qiymatlarini to'ldiring
npm start

If you open http://localhost:3000/health in your browser, it means the server is running.

4. Deploying Online (Using Render.com as an Example)

1. Upload this project to GitHub (create a new repository, push the files).

2. Sign up at https://render.com.

3. New + → Web Service → Select your GitHub repository.

4. Settings:

   • Build Command: npm install

   • Start Command: npm start

5. In the Environment section, add the following:

   • BILLZ_BASE_URL = https://api-admin.billz.ai

   • BILLZ_LOGIN = (your Client ID, e.g., 200400493)

   • BILLZ_SECRET = (your API key)

   • MCP_BRIDGE_SECRET = (a long random string you come up with)

6. Click the Create Web Service button and wait for the deployment to finish.

7. Render will give you an address similar to: https://billz-mcp-server-xxxx.onrender.com

5. Connecting to Claude

1. In Claude, open Customize → Connectors → "+" → Add custom connector (or the organization Owner can do it via Organization Settings).

2. Name: BILLZ

3. Remote MCP server URL: https://billz-mcp-server-xxxx.onrender.com/mcp (it must end with /mcp — this is not a Notion or dashboard link; it is now the address of your own server)

4. In the Advanced settings fields (if it asks for a simple token, not OAuth), enter the value of MCP_BRIDGE_SECRET.

5. Click the Add button.

After that, if you write to Claude: "Show the list of products in BILLZ" or "Get the last 30 days of sales from BILLZ", it will automatically call the billz_get_products or billz_get_orders tools.

6. Security Notes

• Never upload the .env file to GitHub (a public repository) — make sure to add the .env line to the .gitignore file.

• MCP_BRIDGE_SECRET — this protects your server from outsiders. Do not share it with anyone.

• If BILLZ_SECRET is exposed anywhere (e.g., accidentally typed in a chat), immediately revoke it in the BILLZ panel and create a new one.

7. File Structure

billz-mcp-server/
├── package.json          # bog'liqliklar ro'yxati
├── .env.example           # sozlamalar namunasi
├── README.md               # ushbu qo'llanma
└── src/
    ├── billzClient.js     # BILLZ API bilan gaplashish (autentifikatsiya + so'rov)
    └── server.js          # MCP server (Claude bilan gaplashadigan qism)